external-subagent 0.4.1 → 0.5.1

package/cli/main.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { BUSINESS_COMMANDS, PRODUCT_NAME, VERSION, ZCODE_RUNTIME } from './constants.mjs';
+import { BUSINESS_COMMANDS, PRODUCT_NAME, VERSION, zcodeRuntimePath } from './constants.mjs';
 import { CliError } from './errors.mjs';
 import { installHooks, installPlan, runInit } from './install/init.mjs';
 import { nativeBinary } from './install/layout.mjs';
@@ -17,7 +17,12 @@ import { parseConfigArgs } from './commands/config.mjs';
 import { subagentsCommand, parseSubagentsArgs } from './commands/agents.mjs';
 import { parseProfileArgs, parseSpawnArgs, prepareSpawnInput, profileCommand } from './commands/tasks.mjs';
 
-const HELP = `external-subagent ${VERSION}\n\nUsage: external-subagent <command> [options]\n\nCommands:\n  help, version               Show basic product information\n  init [--dry-run] [--resume] [--install-hooks] [--skip-service-start]\n                             Install the standalone daemon service only; bind a\n                             host afterwards with install-plugin or install-mcp\n  hooks install [--dry-run]  Install ZCode policy hooks explicitly\n  install-plugin [codex|zcode] [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the managed host plugin (MCP + skill);\n                             the host defaults to codex, --codex-home is codex-only\n  install-mcp [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the direct Codex MCP TOML binding\n  status, diagnose            Inspect local service and runtime state\n  start, stop                 Bootstrap or boot out the daemon LaunchAgent\n  profile list | profile show <name>\n                             Inspect global spawn profiles (profiles/*.json);\n                             invalid files are reported as path-based warnings,\n                             and warned or duplicate files are excluded from the\n                             available name set\n  backup --output <dir>       Back up retained product data\n  restore --input <dir>       Verify and restore product data\n  uninstall                   Release Codex/ZCode bindings; remove service registration; retain data\n  purge --yes                 Explicitly delete new product data\n`;
+// Hosts that ship a supported service backend and payload: macOS (launchd)
+// and Linux (systemd user services).  The gate is structural, so any other
+// platform is rejected before product paths are resolved or written.
+const SUPPORTED_PLATFORMS = new Set(['darwin', 'linux']);
+
+const HELP = `external-subagent ${VERSION}\n\nUsage: external-subagent <command> [options]\n\nCommands:\n  help, version               Show basic product information\n  init [--dry-run] [--resume] [--install-hooks] [--skip-service-start]\n                             Install the standalone daemon service only; bind a\n                             host afterwards with install-plugin or install-mcp\n  hooks install [--dry-run]  Install ZCode policy hooks explicitly\n  install-plugin [codex|zcode] [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the managed host plugin (MCP + skill);\n                             the host defaults to codex, --codex-home is codex-only\n  install-mcp [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the direct Codex MCP TOML binding\n  status, diagnose            Inspect local service and runtime state\n  start, stop                 Bootstrap or boot out the daemon service\n  profile list | profile show <name>\n                             Inspect global spawn profiles (profiles/*.json);\n                             invalid files are reported as path-based warnings,\n                             and warned or duplicate files are excluded from the\n                             available name set\n  backup --output <dir>       Back up retained product data\n  restore --input <dir>       Verify and restore product data\n  uninstall                   Release Codex/ZCode bindings; remove service registration; retain data\n  purge --yes                 Explicitly delete new product data\n`;
 const DAEMON_HELP = `  config get [key] | config set <key> <value>\n  subagents list | subagents status [subagent] | subagents probe/models [subagent]\n  create/spawn [--profile <name>], wait, list, send, respond, cancel, result, close, observe\n                             Daemon calls accept --json '<object>' or JSON stdin\n                             list JSON requires repository (workspace is an alias)\n                             observe JSON requires only agent_id\n`;
 
 function structuredInput(args, parser) {
@@ -262,7 +267,11 @@ async function diagnose(paths, args) {
     scope: agent ? { agent_id: agent } : { kind: 'global' },
     platform: platform(),
     runtime: {
-      configured_artifact: fileArtifact(ZCODE_RUNTIME, 'cli_packaged_configuration'),
+      // The same platform-aware resolution the service generators use
+      // (constants.mjs): explicit ZCODE_RUNTIME_PATH, then the platform's
+      // conventional installation, then the packaged pin — reported as an
+      // artifact observation, never a probe.
+      configured_artifact: fileArtifact(zcodeRuntimePath(paths.home), 'cli_resolved_configuration'),
       running_identity: null,
       running_identity_source: 'not_observed_by_cli',
     },
@@ -332,7 +341,10 @@ export async function main(args) {
     process.stdout.write(`${VERSION}\n`); return;
   }
   if (command !== 'profile' && !BUSINESS_COMMANDS.has(command)) throw new CliError('UNKNOWN_COMMAND', `unknown command: ${command}`, 2);
-  if (platform() !== 'darwin') throw new CliError('UNSUPPORTED_PLATFORM', `${command} is supported only on macOS`);
+  // macOS and Linux are supported hosts; every other platform (Windows, BSD,
+  // an unknown tuple) is refused structurally before any filesystem side
+  // effect, so an unsupported host never writes HOME state.
+  if (!SUPPORTED_PLATFORMS.has(platform())) throw new CliError('UNSUPPORTED_PLATFORM', `${command} is supported only on macOS and Linux`);
 
   const paths = productPaths();
   if (command === 'init') {
@@ -373,13 +385,15 @@ export async function main(args) {
   if (command === 'status') {
     const verbose = args.includes('--verbose');
     const local = localInstallStatus(paths, { verbose });
-    // `service` is the read-only launchd view (registered job + process);
-    // `daemon_status` stays the RPC view, so a loaded-but-unready or
-    // ready-but-unregistered install reads differently instead of blurring.
-    const serviceRaw = serviceRegistrationStatus();
-    // PID is an implementation detail and may be reused by another process;
-    // keep it out of the ordinary status projection.
-    const { pid: _pid, ...service } = serviceRaw;
+    // `service` is the read-only backend view (launchd registered job or the
+    // systemd user unit's real state — `failed` included, never a fake
+    // healthy) selected by the platform dispatch in service-macos.mjs; a Linux
+    // host without a reachable user manager degrades to an explicit
+    // `unavailable` view with the linger hint instead of failing the whole
+    // read-only command. `daemon_status` stays the RPC view, so a
+    // loaded-but-unready or ready-but-unregistered install reads differently
+    // instead of blurring.
+    const { pid: _pid, ...service } = serviceRegistrationStatus();
     try {
       output({ ...local, service, daemon_status: publicDaemonStatus(await callDaemon(process.env.EXTERNAL_SUBAGENT_SOCKET || paths.socket, 'status', {}), { verbose }) });
     } catch (error) {

package/cli/maintenance.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CliError } from './errors.mjs';
 import { jsonBytes, sha256 } from './fs-atomic.mjs';
-import { productPaths } from './paths.mjs';
+import { platform, productPaths } from './paths.mjs';
 import { bootoutService } from './install/service-macos.mjs';
 
 function copyTree(source, destination, records, root = source) {
@@ -75,20 +75,25 @@ function removeOne(target) {
   }
 }
 
-// Deleting the plist alone leaves a job launchd already loaded running until
-// the next logout (observed live: uninstall reported success while the daemon
-// process, the launchd registration, and the RPC socket all stayed alive).
-// The ES-owned service is therefore booted out — with the bounded
-// removal-confirmation bootoutService owns — before its definition file is
-// removed.  A service that is not registered is not an error (idempotent
-// uninstall); a bootout that cannot complete fails the command rather than
-// deleting the definition out from under a still-running service.
+// Deleting the definition alone leaves a job the service manager already
+// loaded running until the next logout (observed live: uninstall reported
+// success while the daemon process, the launchd registration, and the RPC
+// socket all stayed alive).  The ES-owned service is therefore booted out —
+// with the bounded removal confirmation bootoutService owns on BOTH backends
+// (launchd bootout on macOS, systemctl --user disable --now plus the inactive
+// confirmation on Linux) — before its definition file is removed.  A service
+// that is not registered is not an error (idempotent uninstall); a stop that
+// cannot complete fails the command rather than deleting the definition out
+// from under a still-running service.  `removed_launch_agent` is macOS-only;
+// Linux reports the same removal as `removed_service_definition`.
 export function uninstall(paths = productPaths(), options = {}) {
-  const service = bootoutService(paths, process.getuid(), options);
+  const macos = platform() === 'darwin';
+  const service = bootoutService(paths, process.getuid(), { launchctl: options.launchctl, systemctl: options.systemctl });
+  const removed = removeOne(paths.launchAgent);
   return {
     service_stopped: true,
     service_already_stopped: Boolean(service.already_stopped),
-    removed_launch_agent: removeOne(paths.launchAgent),
+    ...(macos ? { removed_launch_agent: removed } : { removed_service_definition: removed }),
     data_retained: true,
     data: paths.data,
   };

package/cli/paths.mjs

@@ -3,14 +3,16 @@ import path from 'node:path';
 import { LAUNCH_AGENT_LABEL, PRODUCT_NAME } from './constants.mjs';
 import { PLUGIN_NAME } from './install/layout.mjs';
 
-export function platform() {
-  return process.env.EXTERNAL_SUBAGENT_TEST_PLATFORM || process.platform;
+// The process platform, overridable by the EXTERNAL_SUBAGENT_TEST_PLATFORM seam
+// so both layouts are exercisable on any host.  The seam keeps its original
+// meaning: it is a *process platform* override, nothing else.
+export function platform(env = process.env) {
+  return env.EXTERNAL_SUBAGENT_TEST_PLATFORM || process.platform;
 }
 
-// State paths derive from PRODUCT_NAME, so the debug variant gets a fully
-// parallel tree (its own data directory, database, socket, and logs) and
-// never touches the released product's state.
-export function productPaths(home = os.homedir()) {
+// macOS derives the whole tree from `~/Library`; the bytes of every field below
+// are contractually frozen (existing installs must keep resolving their state).
+function darwinProductPaths(home) {
   const data = path.join(home, 'Library', 'Application Support', PRODUCT_NAME);
   return {
     home,
@@ -28,6 +30,52 @@ export function productPaths(home = os.homedir()) {
   };
 }
 
+// XDG Base Directory resolution (D-S02).  A variable selects its directory only
+// when it is a non-empty absolute path; relative or empty values are ignored and
+// the spec fallback under $HOME applies.  Only the three XDG variables the
+// product owns are read — no other user XDG directory is probed.
+function xdgDirectory(env, variable, home, fallback) {
+  const configured = env[variable];
+  if (typeof configured === 'string' && configured !== '' && path.isAbsolute(configured)) {
+    return configured;
+  }
+  return path.join(home, ...fallback);
+}
+
+// Linux keeps the same internal relative layout as macOS (config, install
+// state, database, socket, hook provenance, plugin staging, profiles all live
+// inside the product data directory) so the two platforms stay structurally
+// parallel.  Data and logs follow XDG; the systemd user unit directory is
+// provided for the S03 service backend.
+function linuxProductPaths(home, env) {
+  const data = path.join(xdgDirectory(env, 'XDG_DATA_HOME', home, ['.local', 'share']), PRODUCT_NAME);
+  const logs = path.join(xdgDirectory(env, 'XDG_STATE_HOME', home, ['.local', 'state']), PRODUCT_NAME);
+  const configHome = xdgDirectory(env, 'XDG_CONFIG_HOME', home, ['.config']);
+  return {
+    home,
+    data,
+    config: path.join(data, 'config.json'),
+    state: path.join(data, 'install-state.json'),
+    hookProvenance: path.join(data, 'zcode-agent-hook-provenance.json'),
+    database: path.join(data, `${PRODUCT_NAME}.sqlite3`),
+    socket: path.join(data, `${PRODUCT_NAME}.sock`),
+    logs,
+    launchAgent: path.join(configHome, 'systemd', 'user', `${PRODUCT_NAME}.service`),
+    zcodeConfig: path.join(home, '.zcode', 'cli', 'config.json'),
+    zcodePlugin: path.join(data, 'zcode-plugin', PLUGIN_NAME),
+    profiles: path.join(data, 'profiles'),
+  };
+}
+
+// State paths derive from PRODUCT_NAME, so the debug variant gets a fully
+// parallel tree (its own data directory, database, socket, and logs) and
+// never touches the released product's state.  The layout is selected by the
+// process platform: macOS `~/Library`, every other supported host the XDG
+// baseline.  `zcodeConfig` is `~/.zcode/cli/config.json` on both platforms.
+export function productPaths(home = os.homedir(), env = process.env) {
+  return platform(env) === 'darwin' ? darwinProductPaths(home) : linuxProductPaths(home, env);
+}
+
 // Mirror the daemon's `profiles_directory()` exactly (rpc/profiles.rs):
 // `EXTERNAL_SUBAGENT_CONFIG` wins when it is *exported*, even when exported as
 // an empty string, and only then does `ZCODE_AGENT_CONFIG` apply; presence, not
@@ -35,7 +83,8 @@ export function productPaths(home = os.homedir()) {
 // exported path has no parent in Rust (`Path::new("").parent() == None`), so the
 // daemon loads no profiles directory at all; return null to represent that.
 // Otherwise take the sibling `profiles/` of the config file, or fall back to the
-// product data directory.
+// product data directory (the daemon's data fallback is the same XDG/macOS data
+// root selected here, so both sides resolve one directory).
 
 // Rust `Path::parent()` semantics on Unix, implemented with plain string
 // slicing (never `path.dirname`/`path.join`, which lexically normalise and would
@@ -83,7 +132,7 @@ export function profilesDir(env = {}, home = os.homedir()) {
       break;
     }
   }
-  if (!exported) return path.join(productPaths(home).data, 'profiles');
+  if (!exported) return path.join(productPaths(home, env).data, 'profiles');
   const parent = rustPathParent(envPath);
   if (parent === null) return null;
   return joinProfiles(parent);

package/npm/native/darwin-arm64/payload.json

@@ -1,20 +1,20 @@
 {
   "schema_version": 1,
   "product": "external-subagent",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "platform": "darwin-arm64",
   "files": [
     {
       "name": "external-subagentd",
-      "bytes": 10116128,
+      "bytes": 10075248,
       "mode": "755",
-      "sha256": "9c650b9c096f4060e927eced4d05665749123177e3c7d105a13a8a466633ed77"
+      "sha256": "eb0b1c4ffb4ab44678adf5aa39ee96f61cf09ebdb03b74da9e12cebad2b868f5"
     },
     {
       "name": "external-subagent-mcp",
       "bytes": 935888,
       "mode": "755",
-      "sha256": "e519c71451bc27bf217316c57fe92d82e8e8fc546c13194455ad60dbc0cdc9f7"
+      "sha256": "1dce8a0c5566af2d9b4a12a39ad43c819bcb7f395a1a7c738389e5b0bbd24346"
     }
   ]
 }

package/npm/native/linux-x64/payload.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": 1,
+  "product": "external-subagent",
+  "version": "0.5.1",
+  "platform": "linux-x64",
+  "files": [
+    {
+      "name": "external-subagentd",
+      "bytes": 11452160,
+      "mode": "755",
+      "sha256": "c4f410496c2f9390288cb168e447127c9ee7ec0b47c591bcd84f25f688cad3af"
+    },
+    {
+      "name": "external-subagent-mcp",
+      "bytes": 1025360,
+      "mode": "755",
+      "sha256": "6553125c48dcd1a21554a6dd1181a7cb55d84f874118a1bd5136b5b29e916e60"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "external-subagent",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Manage bounded ZCode, DeepSeek Harness (DSH), Codex, and Google Antigravity (agy) subagent tasks through a local MCP service for any local host (Codex, ZCode, or a custom MCP client)",
   "type": "module",
   "license": "MIT",
@@ -21,10 +21,12 @@
     "agent-tasks"
   ],
   "os": [
-    "darwin"
+    "darwin",
+    "linux"
   ],
   "cpu": [
-    "arm64"
+    "arm64",
+    "x64"
   ],
   "bin": {
     "external-subagent": "bin/external-subagent.mjs",
@@ -52,6 +54,7 @@
     "postpack": "node scripts/release/check-native-tarball.mjs",
     "prepublishOnly": "node scripts/release/check-native-tarball.mjs --staged",
     "test:install": "node --test tests/install/*.test.mjs",
+    "test:release": "node --test tests/release/*.test.mjs",
     "test:affected": "node scripts/test/affected.mjs",
     "check": "node --check bin/external-subagent.mjs && node --check bin/external-subagent-mcp.mjs && node --check bin/external-subagent-debug.mjs && node --check bin/external-subagent-debug-mcp.mjs && node --check cli/main.mjs"
   },

package/plugins/codex/external-subagent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "external-subagent",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Manage bounded external agent tasks through the external-subagent MCP service.",
   "author": { "name": "external-subagent maintainers" },
   "skills": "./skills/",

package/plugins/codex/external-subagent/scripts/policy-verifier.mjs

@@ -25,8 +25,22 @@ const script = hook?.args?.find((candidate) => typeof candidate === 'string' &&
 const guard = events.PreToolUse.find((entry) => entry?.matcher === 'Bash')?.hooks?.find((entry) => entry?.type === 'process')?.args?.[0];
 const audit = events.PostToolUse?.find((entry) => entry?.matcher === 'Bash')?.hooks?.find((entry) => entry?.type === 'process')?.args?.[0];
 if (!script || !fs.statSync(script).isFile() || hook.command !== process.execPath || !guard || !fs.statSync(guard).isFile() || !audit || !fs.statSync(audit).isFile()) process.exit(2);
-const provenancePath = path.join(home, 'Library', 'Application Support', 'external-subagent', 'zcode-agent-hook-provenance.json');
-if (!fs.existsSync(provenancePath)) process.exit(2);
+// The provenance is staged by install-agent-hooks.mjs beside this verifier,
+// inside the product data directory of the probe home. The candidates mirror
+// the daemon's policy_verifier_candidates exactly: the frozen macOS
+// `~/Library/Application Support` bytes on darwin; elsewhere an exported
+// absolute $XDG_DATA_HOME is probed first, then the `~/.local/share` XDG
+// fallback for the scope home.
+const provenanceCandidates = process.platform === 'darwin'
+  ? [path.join(home, 'Library', 'Application Support', 'external-subagent', 'zcode-agent-hook-provenance.json')]
+  : [
+      ...(typeof process.env.XDG_DATA_HOME === 'string' && path.isAbsolute(process.env.XDG_DATA_HOME)
+        ? [path.join(process.env.XDG_DATA_HOME, 'external-subagent', 'zcode-agent-hook-provenance.json')]
+        : []),
+      path.join(home, '.local', 'share', 'external-subagent', 'zcode-agent-hook-provenance.json'),
+    ];
+const provenancePath = provenanceCandidates.find((candidate) => fs.existsSync(candidate));
+if (!provenancePath) process.exit(2);
 const provenance = JSON.parse(fs.readFileSync(provenancePath, 'utf8'));
 const hash = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 const policy = path.resolve(path.dirname(script), '../lib/agent-file-policy.mjs');

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

@@ -1,12 +1,13 @@
 #!/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
+// npm/native/<platform> together with a deterministic payload.json manifest
+// (version, platform, per-file bytes/sha256/mode), where <platform> is derived
+// from the running host (darwin-arm64, linux-x64).  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
+// cargo artifacts are copied under debug names into npm/native-debug/<platform>
 // (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
@@ -20,8 +21,19 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { stageDebugPlugin } from './stage-debug-plugin.mjs';
+import { nativePlatform } from '../../cli/install/layout.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+// The staged directory and the manifest `platform` field derive from the
+// running host through the shared platform table, so one script stages the
+// correct tuple everywhere (release: darwin-arm64, linux-x64) and an
+// unsupported host fails before touching the tree.  The debug variant reuses
+// the same tuple under its parallel native-debug directory.
+const platform = nativePlatform();
+if (platform === null) {
+  process.stderr.write(`no native payload for ${process.platform}-${process.arch}\n`);
+  process.exit(2);
+}
 const variantIndex = process.argv.indexOf('--variant');
 const variant = variantIndex === -1 ? '' : (process.argv[variantIndex + 1] ?? '');
 if (variant !== '' && variant !== 'debug') {
@@ -42,7 +54,7 @@ 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 platformDir = path.join(packageRoot, 'npm', nativeDirName, platform);
 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')]);
@@ -73,7 +85,7 @@ 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;
+  if (manifest.version !== version || manifest.platform !== platform || manifest.product !== productName) return false;
   if ((manifest.profile ?? 'release') !== cargoProfile) return false;
   const inputs = newestInputMs();
   for (const file of manifest.files) {
@@ -121,7 +133,7 @@ for (const [source, name] of binaries) {
   files.push({ name, bytes: bytes.length, mode: '755', sha256: sha256(bytes) });
 }
 
-const manifest = { schema_version: 1, product: productName, version, platform: 'darwin-arm64' };
+const manifest = { schema_version: 1, product: productName, version, platform };
 // The debug profile is recorded so --if-stale can tell a debug-staged payload
 // from a release one; the release manifest stays byte-identical to before.
 if (cargoProfile !== 'release') manifest.profile = cargoProfile;

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

@@ -3,26 +3,47 @@
 //   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
+//   check-native-tarball.mjs --staged        verify only the staged payloads
+//                                             (npm/native/<platform>) against
 //                                             the package version — the publish
 //                                             gate, since `npm publish` packs
 //                                             into a private temp directory no
 //                                             lifecycle script can inspect.
+// A released tarball carries every supported platform payload (darwin-arm64
+// and linux-x64), so both entry sets and both manifests are required in either
+// mode: a tarball missing one platform is rejected.  Version agreement with the
+// packed package is enforced for the running host's payload (prepack rebuilds
+// only the host payload from source) and, in --staged mode, for every staged
+// platform — the merged publish tree where the foreign payload comes from CI's
+// other platform job.  Image checks (Mach-O arm64 / ELF x86-64) and the 755
+// mode check use the same probes and layout table as cli/install/payload.mjs,
+// so this gate cannot drift from what an installed package verifies.
 // 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';
+import { elfArch, machoArch } from '../../cli/install/payload.mjs';
+import { nativePlatform } from '../../cli/install/layout.mjs';
 
 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';
 
+// Every platform the single release tarball ships, and the image identity each
+// payload must carry.  Keeping both lists here (rather than a fixed
+// darwin-arm64 path) is what makes the gate dual-platform.
+const RELEASE_PLATFORMS = Object.freeze(['darwin-arm64', 'linux-x64']);
+const BINARIES = Object.freeze(['external-subagentd', 'external-subagent-mcp']);
+const IMAGE_CHECKS = Object.freeze({
+  'darwin-arm64': { describe: 'Mach-O arm64 executable', probe: machoArch, arch: 'arm64' },
+  'linux-x64': { describe: 'ELF x86-64 executable', probe: elfArch, arch: 'x64' },
+});
+const hostPlatform = nativePlatform();
+
 function findTarball() {
   if (explicit) return explicit;
   const candidates = [];
@@ -57,14 +78,17 @@ if (!stagedOnly) {
       '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',
     ];
+    // Both platform payloads are mandatory: a tarball that ships only one is
+    // rejected here (and by the --staged publish gate) before it can be
+    // published.
+    for (const platform of RELEASE_PLATFORMS) {
+      for (const name of [...BINARIES, 'payload.json']) required.push(`package/npm/native/${platform}/${name}`);
+    }
 
     const listing = spawnSync('tar', ['-tzf', tgz], { encoding: 'utf8' });
     if (listing.status !== 0) {
@@ -85,38 +109,82 @@ if (!stagedOnly) {
     }
 
     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;
+    for (const platform of RELEASE_PLATFORMS) {
+      const manifestText = spawnSync('tar', ['-xzf', tgz, '-O', `package/npm/native/${platform}/payload.json`], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }).stdout;
+      let manifest;
+      try {
+        manifest = JSON.parse(manifestText);
+      } catch (error) {
+        process.stderr.write(`payload manifest for ${platform} is not valid JSON: ${error.message}\n`);
+        failed = true;
+        continue;
+      }
+      if (manifest.product !== 'external-subagent' || manifest.platform !== platform) {
+        process.stderr.write(`payload manifest for ${platform} has an inconsistent identity (${manifest.product}/${manifest.platform})\n`);
+        failed = true;
+      }
+      if (platform === hostPlatform && manifest.version !== packedPackage.version) {
+        process.stderr.write(`payload version ${manifest.version} (${platform}) 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.
+// Staged payload checks: the staged native binaries and the package version
+// must agree right where the tarball is built from.  The publish gate
+// (--staged) checks every platform because CI merges both artifacts into one
+// tree before packing; a plain `npm pack` checks the running host's platform,
+// whose payload prepack rebuilds from source (the foreign platform is required
+// to be present by the tarball entry checks above).
 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`);
+function checkStagedPlatform(platform) {
+  const dir = path.join(process.cwd(), 'npm', 'native', platform);
+  const manifestPath = path.join(dir, 'payload.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    process.stderr.write(`staged ${platform} payload manifest is unavailable: ${error.message}\n`);
+    failed = true;
+    return;
+  }
+  if (manifest.version !== repoPackage.version) {
+    process.stderr.write(`staged ${platform} payload version ${manifest.version} does not match package version ${repoPackage.version}\n`);
+    failed = true;
+  }
+  if (manifest.product !== 'external-subagent') {
+    process.stderr.write(`staged ${platform} payload product ${manifest.product} is not the release payload\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 (manifest.platform !== platform) {
+    process.stderr.write(`staged ${platform} payload manifest declares ${manifest.platform}\n`);
+    failed = true;
+  }
+  const image = IMAGE_CHECKS[platform];
+  for (const name of BINARIES) {
+    const local = path.join(dir, name);
+    let bytes;
+    try {
+      bytes = fs.readFileSync(local);
+    } catch (error) {
+      process.stderr.write(`${platform}/${name} is missing from the staged payload: ${error.code}\n`);
+      failed = true;
+      continue;
+    }
+    if (image.probe(bytes) !== image.arch) {
+      process.stderr.write(`${platform}/${name} is not a ${image.describe}\n`);
+      failed = true;
+    }
+    const mode = (fs.statSync(local).mode & 0o777).toString(8);
+    if (mode !== '755') { process.stderr.write(`${platform}/${name} has release mode ${mode}, expected 755\n`); failed = true; }
+  }
+}
+
+const stagedPlatforms = stagedOnly ? RELEASE_PLATFORMS : (hostPlatform ? [hostPlatform] : []);
+for (const platform of stagedPlatforms) checkStagedPlatform(platform);
+if (stagedPlatforms.length === 0) {
+  note(`no staged release platform for ${process.platform}-${process.arch}; staged payload checks skipped\n`);
 }
 
 if (failed) process.exit(1);

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

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { nativePlatform } from '../../cli/install/layout.mjs';
 
 function run(command, args, options = {}) {
   const result = spawnSync(command, args, { encoding: 'utf8', ...options });
@@ -38,7 +39,11 @@ 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')]) {
+  // The packed payload directory is the running host's tuple (S01), so the
+  // smoke checks the platform it is actually installing rather than a fixed
+  // darwin-arm64 path.
+  const payloadPlatform = nativePlatform() ?? `${process.platform}-${process.arch}`;
+  for (const target of [cli, path.join(prefix, 'bin', 'external-subagent-mcp'), path.join(packageRoot, 'npm', 'native', payloadPlatform, 'external-subagentd')]) {
     fs.accessSync(target, fs.constants.X_OK);
   }
   run(cli, ['version'], { env });