external-subagent 0.4.0 → 0.5.0

package/cli/install/service-macos.mjs

@@ -1,14 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { DAEMON_BIN_NAME, LAUNCH_AGENT_LABEL, ZCODE_RUNTIME } from '../constants.mjs';
+import { DAEMON_BIN_NAME, LAUNCH_AGENT_LABEL, zcodeRuntimePath } from '../constants.mjs';
 import { CliError } from '../errors.mjs';
 import { atomicWrite } from '../fs-atomic.mjs';
 import { nativeBinary } from './layout.mjs';
 import { LAUNCHD_FIXED_PATH } from './path.mjs';
 import { readConfig } from '../config/read.mjs';
+import { platform } from '../paths.mjs';
+import {
+  SYSTEMD_UNIT_NAME, bootstrapServiceSystemd, bootoutServiceSystemd, installServiceUnit,
+  systemdServiceRegistrationStatus,
+} from './service-linux.mjs';
 
-// The one macOS service template for the product daemon.  The plist pins
+// The macOS service backend for the product daemon, plus the platform
+// dispatch into the systemd user backend (service-linux.mjs).  The plist pins
 // absolute payload paths and a fixed PATH so the GUI/launchd environment can
 // never depend on the interactive shell.  Launchctl activation honors the
 // EXTERNAL_SUBAGENT_TEST_NO_LAUNCHCTL seam so fixture runs never load real
@@ -22,7 +28,7 @@ function escapeXml(value) {
 export function runtimeObservations(paths, options = {}) {
   const config = readConfig(paths.config);
   return Object.fromEntries(['zcode', 'dsh', 'codex', 'agy'].map((agent) => {
-    const runtime = agent === 'zcode' ? (options.zcodeRuntime ?? ZCODE_RUNTIME) : config.subagents[agent].runtime_path;
+    const runtime = agent === 'zcode' ? (options.zcodeRuntime ?? zcodeRuntimePath(paths.home)) : config.subagents[agent].runtime_path;
     return [agent, { path: runtime, present: Boolean(runtime && fs.existsSync(runtime)), enabled: config.subagents[agent].enabled }];
   }));
 }
@@ -38,13 +44,14 @@ export function launchAgentPlist(paths, options = {}) {
   const { runtime_path: agyRuntime } = config.subagents.agy;
   const configRevision = config.revision;
   // AUD-005/D1: the standalone service never depends on an unrelated runtime.
-  // The pinned ZCode runtime is forwarded only when that installation exists;
-  // without it the daemon still starts and the zcode adapter fails closed at
-  // spawn ("ZCODE_RUNTIME_PATH is unavailable") instead of the whole service
-  // dying on launchd because --runtime cannot canonicalize.  Installing (or
-  // removing) ZCode later is picked up by the next init, which rewrites the
-  // plist.  The seam exists so tests can pin both branches deterministically.
-  const zcodeRuntime = options.zcodeRuntime ?? ZCODE_RUNTIME;
+  // The pinned ZCode runtime (platform-discovered, constants.mjs) is forwarded
+  // only when that installation exists; without it the daemon still starts and
+  // the zcode adapter fails closed at spawn ("ZCODE_RUNTIME_PATH is
+  // unavailable") instead of the whole service dying on launchd because
+  // --runtime cannot canonicalize.  Installing (or removing) ZCode later is
+  // picked up by the next init, which rewrites the plist.  The seam exists so
+  // tests can pin both branches deterministically.
+  const zcodeRuntime = options.zcodeRuntime ?? zcodeRuntimePath(paths.home);
   const programArguments = [
     `<string>${escapeXml(daemon)}</string>`,
     '<string>--database</string>',
@@ -103,7 +110,7 @@ export function launchctl(args) {
 // A repeat init/start must stay idempotent instead of failing the whole run,
 // so the registration lookup below — the same print/absent discriminator the
 // update owner uses — decides between "already loaded" and a real failure.
-export function serviceRegistrationStatus(uid = process.getuid(), options = {}) {
+export function launchdServiceRegistrationStatus(uid = process.getuid(), options = {}) {
   const control = options.launchctl || launchctl;
   const result = control(['print', `gui/${uid}/${LAUNCH_AGENT_LABEL}`]);
   if (result.skipped) return { query: 'skipped', registered: null, reason: result.reason };
@@ -113,20 +120,20 @@ export function serviceRegistrationStatus(uid = process.getuid(), options = {})
   return { registered: true, state, pid: Number.isInteger(pid) && pid > 0 ? pid : null };
 }
 
-export function bootstrapService(paths, uid = process.getuid(), options = {}) {
+export function bootstrapLaunchdService(paths, uid = process.getuid(), options = {}) {
   const control = options.launchctl || launchctl;
   const alreadyLoaded = (lookup) => ({
     action: 'bootstrap', label: LAUNCH_AGENT_LABEL, already_loaded: true,
     state: lookup.state ?? null, pid: lookup.pid ?? null,
   });
-  const existing = serviceRegistrationStatus(uid, { launchctl: control });
+  const existing = launchdServiceRegistrationStatus(uid, { launchctl: control });
   if (existing.registered) return alreadyLoaded(existing);
   try {
     return control(['bootstrap', `gui/${uid}`, paths.launchAgent]);
   } catch (error) {
     // Another loader (a racing init, or launchd itself re-reading the plist)
     // may have won after the check above; confirm before reporting failure.
-    const loaded = serviceRegistrationStatus(uid, { launchctl: control });
+    const loaded = launchdServiceRegistrationStatus(uid, { launchctl: control });
     if (loaded.registered) return alreadyLoaded(loaded);
     throw error;
   }
@@ -138,9 +145,9 @@ export function bootstrapService(paths, uid = process.getuid(), options = {}) {
 // service unregistered roughly one time in three).  The stop owner therefore
 // confirms the job is actually gone — bounded, with the same print/absent
 // discriminator the update owner's unload uses — before reporting success.
-export function bootoutService(paths, uid = process.getuid(), options = {}) {
+export function bootoutLaunchdService(paths, uid = process.getuid(), options = {}) {
   const control = options.launchctl || launchctl;
-  const existing = serviceRegistrationStatus(uid, { launchctl: control });
+  const existing = launchdServiceRegistrationStatus(uid, { launchctl: control });
   if (!existing.registered) return { action: 'bootout', label: LAUNCH_AGENT_LABEL, already_stopped: true };
   let result;
   try {
@@ -149,15 +156,49 @@ export function bootoutService(paths, uid = process.getuid(), options = {}) {
     // A racing removal (another stop, or launchd itself) may have taken the
     // job out between the registration probe and the bootout; confirm before
     // reporting failure, so a repeated stop stays idempotent.
-    const settled = serviceRegistrationStatus(uid, { launchctl: control });
+    const settled = launchdServiceRegistrationStatus(uid, { launchctl: control });
     if (!settled.registered) return { action: 'bootout', label: LAUNCH_AGENT_LABEL, already_stopped: true };
     throw error;
   }
   const deadline = Date.now() + (options.unloadTimeoutMs ?? 10_000);
   for (;;) {
-    const probe = serviceRegistrationStatus(uid, { launchctl: control });
+    const probe = launchdServiceRegistrationStatus(uid, { launchctl: control });
     if (!probe.registered) return { ...result, label: LAUNCH_AGENT_LABEL, removed: true };
     if (Date.now() >= deadline) throw new CliError('SERVICE_UNLOAD_TIMEOUT', 'launchd service remained registered after bootout');
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
   }
 }
+
+// Platform dispatch (S03): the service backend is selected by the process
+// platform — launchd on macOS, the systemd user manager on Linux — behind the
+// same call surface every caller (init, start/stop, uninstall, status) already
+// uses.  The macOS arms below are the verbatim launchd implementations; the
+// Linux arms carry the same idempotence/removal-confirmation contract through
+// `systemctl --user` (options.systemctl is the injectable seam, the twin of
+// options.launchctl).
+export function serviceRegistrationStatus(uid = process.getuid(), options = {}) {
+  return platform() === 'darwin'
+    ? launchdServiceRegistrationStatus(uid, options)
+    : systemdServiceRegistrationStatus(options);
+}
+
+export function bootstrapService(paths, uid = process.getuid(), options = {}) {
+  return platform() === 'darwin'
+    ? bootstrapLaunchdService(paths, uid, options)
+    : bootstrapServiceSystemd(paths, uid, options);
+}
+
+export function bootoutService(paths, uid = process.getuid(), options = {}) {
+  return platform() === 'darwin'
+    ? bootoutLaunchdService(paths, uid, options)
+    : bootoutServiceSystemd(paths, uid, options);
+}
+
+// The service-definition installer behind init's install-launch-agent step:
+// the launchd plist on macOS, the systemd user unit (0600, absolute verified
+// payload, Restart=always) on Linux, both at paths.launchAgent.
+export function installServiceDefinition(paths, options = {}) {
+  return platform() === 'darwin' ? installLaunchAgent(paths, options) : installServiceUnit(paths, options);
+}
+
+export { SYSTEMD_UNIT_NAME };

package/cli/install/update.mjs

@@ -7,7 +7,7 @@ import { CLI_ENTRY_NAME, DAEMON_BIN_NAME, NATIVE_DIR_NAME } from '../constants.m
 import { reconcileCodexHomes } from './reconcile.mjs';
 import { packageVersion, packageRoot } from './layout.mjs';
 import { loadUpdateState } from './recovery.mjs';
-import { verifyPayload } from './payload.mjs';
+import { normalizePayloadFiles, verifyPayload } from './payload.mjs';
 
 const SCHEMA_VERSION = 2;
 const lockPath = (paths) => path.join(paths.data, 'install.lock');
@@ -113,6 +113,12 @@ export function preflightUpdate(options = {}) {
   if (typeof version !== 'string' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(version) || !available.includes(version)) {
     throw new CliError('PAYLOAD_VERSION_UNAVAILABLE', `requested payload version is unavailable: ${version}`);
   }
+  // Repair a candidate payload mode masked by the installing umask before the
+  // strict verifier runs; the bytes are untouched, so the digest/arch checks
+  // below still bind the candidate to the release manifest.
+  for (const entry of normalizePayloadFiles({ root: candidateRoot, platform: options.platform })) {
+    process.stderr.write(`normalized payload mode ${entry.from} -> ${entry.to} (${entry.name})\n`);
+  }
   const payload = verifyPayload({ root: candidateRoot, platform: options.platform });
   if (version !== payload.version) throw new CliError('PAYLOAD_VERSION_MISMATCH', `requested version ${version} differs from candidate ${payload.version}`);
   // Reject a doomed candidate up front: an unusable stable entry or daemon

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.0",
+  "version": "0.5.0",
   "platform": "darwin-arm64",
   "files": [
     {
       "name": "external-subagentd",
-      "bytes": 10115152,
+      "bytes": 10058880,
       "mode": "755",
-      "sha256": "2fbb31359c60e4834f3ad90733c03942cafe5fd8ab1bc5f2f9512128a8746237"
+      "sha256": "48fe9286f4986cbbadbb460d455ce5f90ca77b10ce2ff1f6f36fd9ab8a949428"
     },
     {
       "name": "external-subagent-mcp",
       "bytes": 935888,
       "mode": "755",
-      "sha256": "73fc786b07873983fb347af756cc316cebb071a14380442777c27c3928e6f2ec"
+      "sha256": "23eb00373ef1c6f4812c81098347d0f95a226bc1f8cfc7610a16ef3fecfe55b7"
     }
   ]
 }

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

@@ -0,0 +1,20 @@
+{
+  "schema_version": 1,
+  "product": "external-subagent",
+  "version": "0.5.0",
+  "platform": "linux-x64",
+  "files": [
+    {
+      "name": "external-subagentd",
+      "bytes": 11414088,
+      "mode": "755",
+      "sha256": "feefc938b692dbf26bb4cbbb25c7799679641a1fb62acbd75327044542ef6418"
+    },
+    {
+      "name": "external-subagent-mcp",
+      "bytes": 1025424,
+      "mode": "755",
+      "sha256": "455bf85256887b87228c495a2207a410e6d07d3399f2d1fa16ca03dd58c665ad"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "external-subagent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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;