external-subagent 0.4.1 → 0.5.0

package/README.md

@@ -16,15 +16,23 @@ independent axes:
 ## Status
 
 The package is published to the public npm registry as
-`external-subagent@0.1.0` (macOS arm64 only; `os`/`cpu` in `package.json`
-reject installation on other platforms at npm install time). `init` installs
-the standalone daemon service only — no host is bound implicitly; hosts are
-bound through the explicit `install-plugin` (Codex or ZCode) /
-`install-mcp` (Codex-only TOML binding) commands. Installing from a packed
-artifact and explicitly initializing to a launchd-resident service
-(idempotent repeat init/start) is live-verified on a real GUI session;
-active-task upgrade and standalone initialization are implemented and
-reviewed.
+`external-subagent@0.5.0` for macOS arm64 and Linux x86_64. `os`/`cpu` in
+`package.json` are independent npm arrays, so npm admits any darwin/linux +
+arm64/x64 tuple at install time; the CLI then enforces the real support at
+first use — a host outside macOS/Linux is rejected with `UNSUPPORTED_PLATFORM`
+before any HOME write, and `darwin-x64`/`linux-arm64` (no native payload) are
+rejected at `init` with `UNSUPPORTED_PAYLOAD_PLATFORM`.
+`init` installs the standalone daemon service only — no host is bound
+implicitly; hosts are bound through the explicit `install-plugin` (Codex or
+ZCode) / `install-mcp` (Codex-only TOML binding) commands. Installing from a
+packed artifact and explicitly initializing to a service is live-verified on
+macOS arm64 (launchd, real GUI session) and on Linux x86_64 (systemd user
+service, Ubuntu; idempotent repeat init/start); active-task upgrade and
+standalone initialization are implemented and reviewed. On Linux x86_64 the
+`codex` and `zcode` subagents are live-verified (OBSERVED), while `dsh` and
+`agy` remain runtime-gated there: their runtimes are not installed on the
+verification host, so they stay disabled by default with an explicit status,
+exactly as on macOS.
 
 All four subagents are **disabled by default** and are enabled per name with
 `external-subagent agents enable <zcode|dsh|codex|agy>`: a successful local probe
@@ -62,12 +70,12 @@ acceptance matrix is recorded in
 
 ## Versioning
 
-The product version has a single source: `package.json` (`0.1.0`). The CLI
+The product version has a single source: `package.json` (`0.5.0`). The CLI
 constant (`cli/constants.mjs`), the daemon crates, and the native payload
 manifest all carry the same version, and `scripts/release/check-native-tarball.mjs`
 enforces payload/package agreement. The managed Codex plugin manifest
 (`plugins/codex/external-subagent/.codex-plugin/plugin.json`, currently
-`0.1.3`) is deliberately **not** tied to the product version: it is codex's
+`0.1.5`) is deliberately **not** tied to the product version: it is codex's
 plugin-cache identity (`plugin@marketplace@version`; under the reserved
 `personal` marketplace name codex resolves the real user root
 machine-globally, ignoring `CODEX_HOME`), which
@@ -80,7 +88,7 @@ intentionally diverge; see
 ## Install
 
 ```
-npm install -g external-subagent     # stages package + payload only (macOS arm64)
+npm install -g external-subagent     # stages package + payload only (macOS arm64, Linux x64)
 external-subagent init               # explicit: standalone daemon service only
 external-subagent install-plugin zcode   # optional host binding (or: install-plugin codex / install-mcp)
 ```
@@ -140,9 +148,13 @@ carries a `hint` field with this format summary.
 ## Publishing
 
 Releases publish from CI via npm Trusted Publishing (OIDC): pushing a `vX.Y.Z`
-tag runs [.github/workflows/npm-publish.yml](.github/workflows/npm-publish.yml)
-on an Apple Silicon runner, which rebuilds the payload, runs the pack gates,
-and publishes with no npm token in the environment — the runner's OIDC
+tag runs [.github/workflows/npm-publish.yml](.github/workflows/npm-publish.yml).
+One tarball carries both platform payloads, so the workflow builds them on two
+runners: the `build-linux` job builds the `linux-x64` payload on Ubuntu and
+uploads it as an artifact, and the `publish` job runs on an Apple Silicon
+runner (where `prepack` rebuilds the `darwin-arm64` payload), merges the Linux
+payload into `npm/native/` before the pack gates and release-path test suites
+run, and publishes with no npm token in the environment — the runner's OIDC
 identity is the credential. npm does not support trusted publishing for a
 package's first release, so the initial version was published manually once
 and the trusted publisher was then linked on npmjs.com; the workflow filename
@@ -165,10 +177,16 @@ completed update whose registered Codex homes only partially rebind reports
 `CODEX_SYNC_PARTIAL` per home and keeps the verified activation; the public
 `stop` confirms launchd removal before returning, and `uninstall` boots out
 the ES-owned service before removing its registration while retaining all
-data. Supported platform: macOS arm64 — `os`/`cpu` in `package.json` make npm
-refuse installation elsewhere up front; the CLI additionally keeps
-`help`/`version` working on other platforms and rejects business commands
-without writing HOME.
+data. Supported platforms: macOS arm64 and Linux x86_64. npm's independent
+`os`/`cpu` arrays only bound the tuple to darwin/linux + arm64/x64 (so
+`darwin-x64` and `linux-arm64` install as well); the CLI keeps `help`/`version`
+working everywhere, rejects a host outside macOS/Linux with
+`UNSUPPORTED_PLATFORM`, and rejects `darwin-x64`/`linux-arm64` at `init` with
+`UNSUPPORTED_PAYLOAD_PLATFORM`, never writing HOME on a rejected host. macOS arm64 is live-verified
+(launchd). Linux x86_64 (Ubuntu, systemd user service) is verified for the
+install/init/service/CLI path and the codex and zcode subagents; `dsh` and
+`agy` remain runtime-gated there (their runtimes are not present on the
+verification host).
 
 See [docs/operations.md](docs/operations.md) for service control, PATH
 behavior, the Codex homes registry, backup/removal, and release checks; and

package/bin/external-subagent-debug-mcp.mjs

@@ -2,4 +2,5 @@
 // Debug-variant MCP facade entry: selects the debug payload before
 // delegating to the shared spawn shim.
 process.env.EXTERNAL_SUBAGENT_VARIANT = 'debug';
-await import('./external-subagent-mcp.mjs');
+const { runMcpFacade } = await import('./external-subagent-mcp.mjs');
+runMcpFacade();

package/bin/external-subagent-mcp.mjs

@@ -1,20 +1,45 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { nativePlatform } from '../cli/install/layout.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
 // The debug shims set EXTERNAL_SUBAGENT_VARIANT before re-entering this file,
 // so the facade resolves to the variant payload staged beside the release one.
-const debug = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
-const facade = path.join(packageRoot, 'npm', debug ? 'native-debug' : 'native', 'darwin-arm64',
-  debug ? 'external-subagent-debug-mcp' : 'external-subagent-mcp');
-const child = spawn(facade, process.argv.slice(2), { stdio: 'inherit', env: process.env });
-child.on('error', (error) => {
-  console.error(error.message);
-  process.exitCode = 1;
-});
-child.on('exit', (code, signal) => {
-  process.exitCode = code ?? (signal ? 1 : 0);
-});
+// The platform tuple derives from the running host (falling back to the raw
+// process tuple on an unsupported host so the diagnostic names the path it
+// tried), matching cli/install/layout.mjs — a linux-x64 install must spawn the
+// linux-x64 payload, never a hard-coded macOS directory.
+export function mcpFacadePath(
+  platform = nativePlatform() ?? `${process.platform}-${process.arch}`,
+  debug = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug',
+) {
+  return path.join(packageRoot, 'npm', debug ? 'native-debug' : 'native', platform,
+    debug ? 'external-subagent-debug-mcp' : 'external-subagent-mcp');
+}
+
+export function runMcpFacade() {
+  const child = spawn(mcpFacadePath(), process.argv.slice(2), { stdio: 'inherit', env: process.env });
+  child.on('error', (error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+  child.on('exit', (code, signal) => {
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
+}
+
+// Launch only when this shim is the process entry point (directly or through
+// an npm bin symlink).  Importing it — the debug shim does so explicitly, and
+// the tests import the pure path resolver — must never spawn a facade.
+function isEntryPoint() {
+  if (process.argv[1] === undefined) return false;
+  try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+}
+
+if (isEntryPoint()) runMcpFacade();

package/cli/commands/config.mjs

@@ -5,6 +5,7 @@ import { CliError } from '../errors.mjs';
 import { atomicWrite } from '../fs-atomic.mjs';
 import { hasInstalledService } from '../install/service-activation.mjs';
 import { launchAgentPlist } from '../install/service-macos.mjs';
+import { platform } from '../paths.mjs';
 
 const CONFIG_INPUT_FIELDS = new Set(['operation', 'patch', 'key']);
 const GET_KEYS = new Set([
@@ -94,8 +95,12 @@ export function parseConfigArgs(args) {
 // launchd (subagent homes, config revision), so every successful write also
 // regenerates the service definition from the new config.  Only the file is
 // rewritten — launchd picks the environment up at its next load, so a running
-// daemon is never restarted or disturbed here.
+// daemon is never restarted or disturbed here.  The launchd plist is macOS
+// only; the Linux systemd unit is re-rendered by the S03 service backend, so a
+// Linux config write refreshes nothing yet instead of writing a plist to the
+// unit path.
 function refreshServiceDefinition(paths) {
+  if (platform() !== 'darwin') return false;
   if (!hasInstalledService(paths)) return false;
   atomicWrite(paths.launchAgent, launchAgentPlist(paths), 0o600);
   return true;

package/cli/commands/daemon.mjs

@@ -2,9 +2,13 @@ import fs from 'node:fs';
 import { bootoutService, bootstrapService } from '../install/service-macos.mjs';
 import { loadCodexHomes } from '../install/reconcile.mjs';
 import { verifyPayload } from '../install/payload.mjs';
+import { platform } from '../paths.mjs';
 
 // Daemon/service command surface: explicit start/stop through the managed
-// LaunchAgent, and the local installation summary consumed by `status`.
+// service definition (launchd bootstrap/bootout on macOS, systemctl --user
+// daemon-reload+enable --now / disable --now on Linux, via the platform
+// dispatch in service-macos.mjs), and the local installation summary consumed
+// by `status`.
 
 export function startDaemon(paths) {
   return bootstrapService(paths);
@@ -23,9 +27,15 @@ export function localInstallStatus(paths, { verbose = false } = {}) {
   const publicPayload = verbose
     ? payload
     : { status: payload.status, platform: payload.platform, version: payload.version };
+  // The service-definition path is the macOS LaunchAgent plist or the Linux
+  // systemd user unit (paths.mjs).  The reported field stays platform-truthful
+  // so a Linux install never reads as a launchd agent.
+  const serviceDefinition = platform() === 'darwin'
+    ? { launch_agent: fs.existsSync(paths.launchAgent) }
+    : { service_definition: fs.existsSync(paths.launchAgent) };
   return {
     installed: fs.existsSync(paths.state),
-    launch_agent: fs.existsSync(paths.launchAgent),
+    ...serviceDefinition,
     data: fs.existsSync(paths.data),
     payload: publicPayload,
     // Home paths are installation internals; status reports only the

package/cli/config/write.mjs

@@ -12,13 +12,31 @@ export function writeConfig(file, value) {
   return config;
 }
 
+// The read-modify-write config transaction holds an exclusive lock on
+// `<config>.lock` for its whole duration. The lock is owned by a helper
+// process so a crashed writer releases it automatically: the helper acquires
+// the lock, creates a `ready` acknowledgement, then holds the lock until this
+// process kills the helper group. macOS uses lockf and Linux uses flock — both
+// take an exclusive advisory lock on a file, run a command while holding it,
+// and give up after a bounded wait, so the timeout/mutual-exclusion/failure
+// semantics are equivalent. The binary is chosen by the host OS (a real
+// capability), not by the EXTERNAL_SUBAGENT_TEST_PLATFORM layout seam.
+const LOCK_TIMEOUT_SECONDS = 2;
+const LOCK_READY_SCRIPT = 'ready="$1"; parent="$2"; printf ready > "$ready"; while kill -0 "$parent" 2>/dev/null; do sleep 0.05; done';
+
+export function lockHelperInvocation(lock, ready, platform = process.platform) {
+  const tail = ['/bin/sh', '-c', LOCK_READY_SCRIPT, 'external-subagent-lock', ready, String(process.pid)];
+  return platform === 'darwin'
+    ? { command: '/usr/bin/lockf', args: ['-t', String(LOCK_TIMEOUT_SECONDS), lock, ...tail] }
+    : { command: '/usr/bin/flock', args: ['-w', String(LOCK_TIMEOUT_SECONDS), lock, ...tail] };
+}
+
 export function updateConfig(file, updater) {
   const lock = `${path.resolve(file)}.lock`;
   fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
   const ready = `${lock}.${process.pid}.${Date.now()}.ready`;
-  const helper = spawn('/usr/bin/lockf', ['-t', '2', lock, '/bin/sh', '-c',
-    'ready="$1"; parent="$2"; printf ready > "$ready"; while kill -0 "$parent" 2>/dev/null; do sleep 0.05; done',
-    'external-subagent-lock', ready, String(process.pid)], { stdio: 'ignore', detached: true });
+  const { command, args } = lockHelperInvocation(lock, ready);
+  const helper = spawn(command, args, { stdio: 'ignore', detached: true });
   const wait = new Int32Array(new SharedArrayBuffer(4));
   const deadline = Date.now() + 2500;
   while (!fs.existsSync(ready)) {

package/cli/constants.mjs

@@ -4,11 +4,15 @@
 // debug build beside the released product without touching it.  The token is
 // read once at module load; the debug bin shims set it before importing the
 // CLI, so every derived name below is stable for the process lifetime.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
 const IS_DEBUG_VARIANT = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
 
 export const PRODUCT_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug' : 'external-subagent';
 export const PRODUCT_ID = IS_DEBUG_VARIANT ? 'external_subagent_debug' : 'external_subagent';
-export const VERSION = '0.4.1';
+export const VERSION = '0.5.0';
 export const LAUNCH_AGENT_LABEL = IS_DEBUG_VARIANT ? 'com.external-subagent-debug.daemon' : 'com.external-subagent.daemon';
 export const DAEMON_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debugd' : 'external-subagentd';
 export const MCP_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug-mcp' : 'external-subagent-mcp';
@@ -16,6 +20,36 @@ export const NATIVE_DIR_NAME = IS_DEBUG_VARIANT ? 'native-debug' : 'native';
 export const CLI_ENTRY_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug.mjs' : 'external-subagent.mjs';
 export const ZCODE_RUNTIME = '/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs';
 
+// The zcode runtime the CLI pins for the daemon, resolved per installation:
+// explicit configuration first, then the platform's conventional location,
+// and — when neither yields a file — the packaged macOS constant, reported
+// honestly as an absent pinned location (presence is the caller's
+// `fs.existsSync` observation, never an assertion).
+//   explicit   ZCODE_RUNTIME_PATH, the same variable the daemon itself
+//              resolves (external-subagentd --runtime / ZCODE_RUNTIME_PATH).
+//              A configured-but-absent path is returned verbatim; forwarding
+//              stays presence-gated so the daemon never starts against a
+//              --runtime that is not a regular file.
+//   darwin     the app bundle resource (frozen bytes above).
+//   linux      the ZCode server runtime the desktop's attached-remote flow
+//              deploys under `~/.zcode/server` (`agents/glm/zcode.cjs`) —
+//              the same default root the official `zcode-agent` launcher
+//              resolves (OBSERVED 2026-10-09; docs/compatibility/zcode.md).
+//              The deployment's ZCODE_SERVER_RUNTIME_ROOT variable is
+//              deliberately NOT consulted: service generation must stay
+//              independent of the interactive shell environment (the same
+//              design the fixed unit PATH follows), and the product home
+//              already owns `~/.zcode`.
+export function zcodeRuntimePath(home = os.homedir(), env = process.env) {
+  const configured = env.ZCODE_RUNTIME_PATH;
+  if (typeof configured === 'string' && configured !== '') return configured;
+  // The process-platform seam, the same expression cli/paths.mjs owns;
+  // duplicated here because paths.mjs imports this module (no import cycle).
+  if ((env.EXTERNAL_SUBAGENT_TEST_PLATFORM || process.platform) === 'darwin') return ZCODE_RUNTIME;
+  const conventional = path.join(home, '.zcode', 'server', 'agents', 'glm', 'zcode.cjs');
+  return fs.existsSync(conventional) ? conventional : ZCODE_RUNTIME;
+}
+
 export const BUSINESS_COMMANDS = new Set([
   'init', 'hooks', 'status', 'diagnose', 'backup', 'restore', 'start', 'stop',
   'uninstall', 'purge', 'install-plugin', 'install-mcp', 'create', 'spawn', 'wait', 'list', 'send',

package/cli/install/init.mjs

@@ -1,16 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { LAUNCH_AGENT_LABEL } from '../constants.mjs';
+import { LAUNCH_AGENT_LABEL, NATIVE_DIR_NAME } from '../constants.mjs';
 import { CliError } from '../errors.mjs';
+import { platform } from '../paths.mjs';
 import { parseConfig } from '../config/read.mjs';
 import { writeConfig } from '../config/write.mjs';
-import { verifyPayload } from './payload.mjs';
+import { normalizePayloadFiles, verifyPayload } from './payload.mjs';
 import { pathReport } from './path.mjs';
 import { packageRoot, payloadManifestPath } from './layout.mjs';
 import { updateInstallation } from './update.mjs';
 import { loadInstallState, markInstallStep, removeCreatedDirectories, rollbackFiles, snapshotFile } from './recovery.mjs';
-import { bootstrapService, bootoutService, installLaunchAgent, runtimeObservations } from './service-macos.mjs';
+import { SYSTEMD_UNIT_NAME, bootstrapService, bootoutService, installServiceDefinition, runtimeObservations } from './service-macos.mjs';
 
 // Standalone-install coordination (S05, AUD-005 decision D1).  A plain npm
 // install only stages the package and payload; an explicit `init` installs
@@ -20,8 +21,12 @@ import { bootstrapService, bootoutService, installLaunchAgent, runtimeObservatio
 //   check-path         PATH findings are reported, never written
 //   create-data        private data/log directories
 //   write-product-config  republish the current agent config schema
-//   install-launch-agent  the one macOS service template
-//   start-service      launchctl bootstrap (best-effort, reported)
+//   install-launch-agent  the one service template: the launchd LaunchAgent
+//                      plist on macOS, the systemd user unit on Linux (the
+//                      step id predates the Linux backend and stays stable so
+//                      resume journals keep matching)
+//   start-service      launchctl bootstrap / systemctl --user daemon-reload +
+//                      enable --now (best-effort, reported)
 //   publish-active-payload  the verified active identity and retained bytes
 //                      (B-3): a successful init establishes the version and
 //                      retention baseline itself, so the standard `npm A ->
@@ -49,14 +54,20 @@ function hookInstallerPath() {
 }
 
 export function installPlan(paths, options = {}) {
-  const manifest = payloadManifestPath() ?? path.join(packageRoot(), 'npm', 'native', 'darwin-arm64', 'payload.json');
+  // The plan reports the payload the verifier will read.  When the running
+  // tuple has a supported payload this is the resolved manifest path; on an
+  // unsupported host the fallback derives the same tuple from the process so
+  // the reported path matches the layout instead of a hard-coded platform.
+  const manifest = payloadManifestPath()
+    ?? path.join(packageRoot(), 'npm', NATIVE_DIR_NAME, `${process.platform}-${process.arch}`, 'payload.json');
+  const darwin = platform() === 'darwin';
   const plan = [
     { id: 'verify-payload', action: 'verify staged native payload', path: manifest },
     { id: 'check-path', action: 'report PATH availability without writing profiles' },
     { id: 'create-data', action: 'create private product data and log directories', paths: [paths.data, paths.logs] },
     { id: 'write-product-config', action: 'republish the product agent config schema', path: paths.config },
-    { id: 'install-launch-agent', action: 'install daemon LaunchAgent', path: paths.launchAgent, label: LAUNCH_AGENT_LABEL },
-    { id: 'start-service', action: 'bootstrap the daemon service', path: paths.launchAgent, label: LAUNCH_AGENT_LABEL },
+    { id: 'install-launch-agent', action: darwin ? 'install daemon LaunchAgent' : 'install daemon systemd user unit', path: paths.launchAgent, ...(darwin ? { label: LAUNCH_AGENT_LABEL } : { unit: SYSTEMD_UNIT_NAME }) },
+    { id: 'start-service', action: darwin ? 'bootstrap the daemon service' : 'enable and start the daemon service', path: paths.launchAgent, ...(darwin ? { label: LAUNCH_AGENT_LABEL } : { unit: SYSTEMD_UNIT_NAME }) },
     { id: 'publish-active-payload', action: 'publish the verified active payload and retained-byte baseline', path: paths.state },
   ];
   if (options.installHooks) plan.splice(plan.findIndex((step) => step.id === 'publish-active-payload'), 0, { id: 'install-hooks', action: 'install ZCode policy hooks', path: paths.zcodeConfig, provenance: paths.hookProvenance });
@@ -82,6 +93,14 @@ export function runInit(options = {}) {
   if (options.dryRun) return { dry_run: true, plan };
 
   const skipPayload = Boolean(options.skipPayloadProbe);
+  if (!skipPayload) {
+    // Repair an extraction mode masked by the installer's umask before the
+    // strict verify-payload gate reads the staged files (a 0775 extract from a
+    // 0755 archive is a real npm-install artifact, not a payload defect).
+    for (const entry of normalizePayloadFiles()) {
+      process.stderr.write(`normalized payload mode ${entry.from} -> ${entry.to} (${entry.name})\n`);
+    }
+  }
   const payload = skipPayload ? { status: 'skipped', platform: null, version: null, files: [] } : verifyPayload();
   const pathFindings = pathReport();
 
@@ -139,12 +158,12 @@ export function runInit(options = {}) {
       mark('write-product-config');
     }
     if (!completed.has('install-launch-agent')) {
-      installLaunchAgent(paths);
+      installServiceDefinition(paths);
       failAt('install-launch-agent');
       mark('install-launch-agent');
     }
     if (!completed.has('start-service') && !options.skipServiceStart) {
-      service = bootstrapService(paths, process.getuid(), { launchctl: options.launchctl });
+      service = bootstrapService(paths, process.getuid(), { launchctl: options.launchctl, systemctl: options.systemctl });
       serviceLoadedByThisRun = !service.skipped && !service.already_loaded;
       mark('start-service');
     }
@@ -183,7 +202,7 @@ export function runInit(options = {}) {
       ...removeCreatedDirectories(directories),
     ];
     if (serviceLoadedByThisRun) {
-      try { bootoutService(paths, process.getuid(), { launchctl: options.launchctl }); } catch (bootoutError) {
+      try { bootoutService(paths, process.getuid(), { launchctl: options.launchctl, systemctl: options.systemctl }); } catch (bootoutError) {
         rollbackErrors.push(`service rollback (bootout) failed: ${bootoutError.message}`);
       }
     }

package/cli/install/layout.mjs

@@ -10,7 +10,14 @@ import { DAEMON_BIN_NAME, MCP_BIN_NAME, NATIVE_DIR_NAME, PRODUCT_NAME, VERSION }
 // constants.mjs, so the debug variant resolves its own payload directory,
 // binary names, and plugin source without a parallel code path.
 export const PLUGIN_NAME = PRODUCT_NAME;
-export const NATIVE_PLATFORM = 'darwin-arm64';
+// Every platform tuple that ships a prebuilt payload maps to its own staged
+// directory name.  The tuple is the package's platform identity: the payload
+// directory, the manifest `platform` field, and the image check in
+// payload.mjs all key off the same value.  A tuple outside this table has no
+// payload and is rejected by the installer, never silently downgraded.
+// NATIVE_PLATFORM stays the reference platform (the released macOS identity).
+export const NATIVE_PLATFORMS = Object.freeze(['darwin-arm64', 'linux-x64']);
+export const NATIVE_PLATFORM = NATIVE_PLATFORMS[0];
 export const NATIVE_BINARIES = Object.freeze([DAEMON_BIN_NAME, MCP_BIN_NAME]);
 
 export function packageRoot() {
@@ -18,12 +25,12 @@ export function packageRoot() {
 }
 
 export function nativePlatform(platform = process.platform, arch = process.arch) {
-  if (platform === 'darwin' && arch === 'arm64') return NATIVE_PLATFORM;
-  return null;
+  const tuple = `${platform}-${arch}`;
+  return NATIVE_PLATFORMS.includes(tuple) ? tuple : null;
 }
 
 export function nativePayloadDir(platform = nativePlatform()) {
-  if (platform !== NATIVE_PLATFORM) return null;
+  if (!NATIVE_PLATFORMS.includes(platform)) return null;
   return path.join(packageRoot(), 'npm', NATIVE_DIR_NAME, platform);
 }
 

package/cli/install/path.mjs

@@ -1,13 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { nativeBinary } from './layout.mjs';
+import { platform } from '../paths.mjs';
 
-// The launchd/GUI environment does not inherit the interactive shell PATH.
-// Every managed entry point therefore resolves to an absolute file inside the
-// installed package, and the fixed PATH below is only what the daemon itself
-// may use to locate system tools.  This module never writes user profiles;
-// PATH findings are reported so an explicit repair stays a user decision.
+// The launchd/GUI and systemd/user-manager environments do not inherit the
+// interactive shell PATH.  Every managed entry point therefore resolves to an
+// absolute file inside the installed package, and the fixed PATHs below are
+// only what the daemon itself may use to locate system tools.  This module
+// never writes user profiles; PATH findings are reported so an explicit
+// repair stays a user decision.
 export const LAUNCHD_FIXED_PATH = '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin';
+// The Linux fixed set covers systemctl and the payload's system-tool
+// dependencies.  systemdServicePath() below appends the interpreter directory
+// of the Node that rendered the unit, so a persisted shim-style subagent
+// runtime (an nvm-installed Codex launcher) resolves `node` from the service
+// environment instead of relying on the interactive shell PATH.
+export const SYSTEMD_FIXED_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+
+// The Linux service PATH is the fixed system-tool set plus the interpreter
+// directory of the node that rendered the unit.  The persisted Codex runtime
+// is commonly an nvm-installed Node launcher whose `#!/usr/bin/env node`
+// shebang resolves `node` from PATH; without that directory the
+// systemd-managed daemon cannot execute it.  This mirrors the macOS fixed PATH
+// carrying the Homebrew bin that holds its own `node`.  The appended directory
+// is absolute and newline-free by construction, so the unit generator's
+// assertUnitLineSafe admits it unconditionally.
+export function systemdServicePath() {
+  return `${SYSTEMD_FIXED_PATH}:${path.dirname(process.execPath)}`;
+}
+
+export function fixedServicePath(env = process.env) {
+  return platform(env) === 'darwin' ? LAUNCHD_FIXED_PATH : systemdServicePath();
+}
 
 export function which(name, env = process.env) {
   const searchPath = (env.PATH || '').split(path.delimiter).filter(Boolean);
@@ -25,17 +49,18 @@ export function pathReport(options = {}) {
   const env = options.env || process.env;
   const daemon = nativeBinary('external-subagentd');
   const facade = nativeBinary('external-subagent-mcp');
+  const darwin = platform(env) === 'darwin';
   return {
     shell: {
       path: env.PATH || null,
       cli_on_path: which('external-subagent', env),
       mcp_on_path: which('external-subagent-mcp', env),
     },
-    launchd: {
-      path: LAUNCHD_FIXED_PATH,
-      daemon_entry: daemon,
-      mcp_entry: facade,
-    },
+    // The fixed service-environment PATH, keyed by the backend that owns it
+    // so the report never calls a systemd unit "launchd".
+    ...(darwin
+      ? { launchd: { path: LAUNCHD_FIXED_PATH, daemon_entry: daemon, mcp_entry: facade } }
+      : { systemd: { path: systemdServicePath(), daemon_entry: daemon, mcp_entry: facade } }),
     stable_entries_absolute: Boolean(daemon && facade && path.isAbsolute(daemon) && path.isAbsolute(facade)),
     shell_profile_writes: 'none',
     node_executable: process.execPath,

package/cli/install/payload.mjs

@@ -4,11 +4,25 @@ import { CliError } from '../errors.mjs';
 import { sha256 } from '../fs-atomic.mjs';
 import { NATIVE_DIR_NAME, PRODUCT_NAME } from '../constants.mjs';
 import {
-  NATIVE_PLATFORM, cliVersion, nativePayloadDir, nativePlatform, packageVersion, payloadManifestPath,
+  NATIVE_PLATFORMS, cliVersion, nativePayloadDir, nativePlatform, packageVersion, payloadManifestPath,
 } from './layout.mjs';
 
 const MH_MAGIC_64 = 0xfeedfacf;
 const CPU_TYPE_ARM64 = 0x0100000c;
+// The single executable mode every released payload file must carry.
+const RELEASE_FILE_MODE = 0o755;
+
+// ELF64 header identity, read little-endian:
+//   e_ident[0..3] = 0x7f 'E' 'L' 'F' (0x464c457f as a LE uint32)
+//   e_ident[4]    = EI_CLASS  (2 = ELFCLASS64)
+//   e_ident[5]    = EI_DATA   (1 = ELFDATA2LSB)
+//   e_machine     = uint16 at offset 18 (0x3e = EM_X86_64)
+const ELF_MAGIC = 0x464c457f;
+const ELFCLASS64 = 2;
+const ELFDATA2LSB = 1;
+const EM_X86_64 = 0x3e;
+const ELF_E_MACHINE_OFFSET = 18;
+const ELF_HEADER_MIN_BYTES = ELF_E_MACHINE_OFFSET + 2;
 
 export function machoArch(bytes) {
   if (bytes.length < 8) return null;
@@ -16,6 +30,25 @@ export function machoArch(bytes) {
   return bytes.readUInt32LE(4) === CPU_TYPE_ARM64 ? 'arm64' : null;
 }
 
+// The Linux image check mirrors machoArch: only a 64-bit little-endian x86-64
+// ELF is a supported payload.  A truncated header (shorter than e_machine), a
+// 32-bit or big-endian image, or any other machine returns null and is
+// rejected as an unsupported architecture.
+export function elfArch(bytes) {
+  if (bytes.length < ELF_HEADER_MIN_BYTES) return null;
+  if (bytes.readUInt32LE(0) !== ELF_MAGIC) return null;
+  if (bytes[4] !== ELFCLASS64 || bytes[5] !== ELFDATA2LSB) return null;
+  return bytes.readUInt16LE(ELF_E_MACHINE_OFFSET) === EM_X86_64 ? 'x64' : null;
+}
+
+// Each supported platform has exactly one image identity.  verifyPayload reads
+// the tuple once and uses the paired probe, so a valid image of the *other*
+// platform can never satisfy this one.
+const IMAGE_CHECKS = Object.freeze({
+  'darwin-arm64': { arch: 'arm64', image: 'Mach-O arm64 image', probe: machoArch },
+  'linux-x64': { arch: 'x64', image: 'ELF x86-64 image', probe: elfArch },
+});
+
 export function readPayloadManifest(options = {}) {
   const platform = options.platform || nativePlatform();
   const root = options.root || undefined;
@@ -41,9 +74,10 @@ export function readPayloadManifest(options = {}) {
 // defect, never a silent downgrade path.
 export function verifyPayload(options = {}) {
   const platform = options.platform || nativePlatform();
-  if (platform === null) {
-    throw new CliError('UNSUPPORTED_PAYLOAD_PLATFORM', `no native payload exists for ${process.platform}-${process.arch}; supported platforms: ${NATIVE_PLATFORM}`);
+  if (!NATIVE_PLATFORMS.includes(platform)) {
+    throw new CliError('UNSUPPORTED_PAYLOAD_PLATFORM', `no native payload exists for ${platform ?? `${process.platform}-${process.arch}`}; supported platforms: ${NATIVE_PLATFORMS.join(', ')}`);
   }
+  const image = IMAGE_CHECKS[platform];
   const manifest = readPayloadManifest({ platform, root: options.root });
   if (manifest.platform !== platform) {
     throw new CliError('PAYLOAD_PLATFORM_MISMATCH', `payload manifest declares ${manifest.platform}, expected ${platform}`);
@@ -74,11 +108,57 @@ export function verifyPayload(options = {}) {
     if (bytes.length !== record.bytes || sha256(bytes) !== record.sha256) {
       throw new CliError('PAYLOAD_DIGEST_MISMATCH', `native payload file ${record.name} does not match the release digest`);
     }
-    const arch = machoArch(bytes);
-    if (arch !== 'arm64') {
-      throw new CliError('PAYLOAD_ARCH_UNSUPPORTED', `native payload file ${record.name} is not a Mach-O arm64 image`);
+    const arch = image.probe(bytes);
+    if (arch !== image.arch) {
+      throw new CliError('PAYLOAD_ARCH_UNSUPPORTED', `native payload file ${record.name} is not a ${image.image}`);
     }
     return { name: record.name, bytes: bytes.length, mode: '755', sha256: record.sha256, arch };
   });
   return { status: 'verified', platform, version: manifest.version, files };
 }
+
+// npm materializes the packaged payload with the permission recorded in the
+// tarball, masked by the installing process's umask.  A host running under a
+// permissive umask (e.g. 0002) can therefore extract an archived 0755 binary
+// as 0775, and the strict gate in verifyPayload below rejects it as
+// PAYLOAD_PERMISSIONS_INVALID — correct, since a group/world-writable native
+// binary is an installation defect and the gate must never be loosened.  The
+// install paths instead repair the extracted mode before verification: only
+// the permission is restored, the bytes are untouched, and the digest/arch
+// checks still run.  Returns true iff the mode actually changed; a missing or
+// non-regular file (directory, symlink) is never chmodded and returns false so
+// verifyPayload keeps owning that rejection.
+export function normalizePayloadMode(target) {
+  let stat;
+  try { stat = fs.lstatSync(target); } catch { return false; }
+  if (!stat.isFile() || stat.isSymbolicLink()) return false;
+  if ((stat.mode & 0o777) === RELEASE_FILE_MODE) return false;
+  fs.chmodSync(target, RELEASE_FILE_MODE);
+  return true;
+}
+
+// Normalize every payload file the manifest names, exactly the set and order
+// verifyPayload will read.  An absent/invalid manifest or an unreadable file is
+// left for verifyPayload to reject with its own code — this helper never turns
+// a rejection into a pass.  Returns the repaired entries with their prior octal
+// mode so the install step can report what it changed.
+export function normalizePayloadFiles(options = {}) {
+  const platform = options.platform || nativePlatform();
+  if (!NATIVE_PLATFORMS.includes(platform)) return [];
+  let manifest;
+  try { manifest = readPayloadManifest({ platform, root: options.root }); } catch { return []; }
+  const dir = options.root
+    ? path.join(options.root, 'npm', NATIVE_DIR_NAME, platform)
+    : nativePayloadDir(platform);
+  const normalized = [];
+  for (const record of manifest.files) {
+    if (!record || typeof record.name !== 'string' || path.basename(record.name) !== record.name || record.name.includes('..')) continue;
+    const target = path.join(dir, record.name);
+    let stat;
+    try { stat = fs.lstatSync(target); } catch { continue; }
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    const before = stat.mode & 0o777;
+    if (normalizePayloadMode(target)) normalized.push({ name: record.name, from: before.toString(8).padStart(3, '0'), to: '755' });
+  }
+  return normalized;
+}