external-subagent 0.4.0 → 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)
 ```
@@ -91,12 +99,62 @@ stale or missing binaries) and `postpack` runs the static tarball checks. A
 development checkout packs the same way (`npm pack` after `cargo` is
 available); see [docs/operations.md](docs/operations.md) for release checks.
 
+## Spawn profiles
+
+A spawn profile is a named JSON preset for the spawn inputs, stored as one
+JSON file per profile in the `profiles/` directory next to `config.json`
+(`~/Library/Application Support/external-subagent/profiles/` by default;
+`profile list` reports the exact path in use). Every `*.json` file in the
+directory is discovered by its `name` field; the same name defined in two
+files is rejected, and invalid files are reported as warnings and excluded
+from the available set.
+
+```json
+{
+  "name": "codex-yolo",
+  "subagent": "codex",
+  "model": "gpt-5",
+  "permission_mode": "yolo",
+  "developer_instructions": "Always reply in English."
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Required, unique across files; trimmed, non-empty, at most 128 bytes |
+| `subagent` | `zcode`, `dsh`, `codex`, or `agy` |
+| `model` | Model token, named per target: `dsh` wants `provider:model`, `zcode` accepts `provider/model` or a bare token, `codex` and `agy` take a bare slug |
+| `effort` | Effort token; some runtime models require one (for example `agy` rejects `gemini-3.8-flash` without `--effort`) and the spawn error surfaces the runtime's message verbatim |
+| `permission_mode` | `build`, `edit`, `plan`, or `yolo`; defaults to `build` when unset |
+| `developer_instructions` | Free-form instructions, delivered as described below |
+
+`--profile` cannot be combined with `--subagent`, `--model`, `--effort`, or
+`--permission_mode`; put those in the profile JSON or omit `profile`. Fields
+left out of the profile fall back to the same defaults as an unprofiled
+spawn. `developer_instructions` rides the codex runtime's native
+`developerInstructions` channel when the effective subagent is `codex`; every
+other subagent receives it silently concatenated in front of the prompt:
+
+```
+Developer Instructions: {developer_instructions}
+----------
+{prompt}
+```
+
+Inspect what is loaded with `external-subagent profile list` and
+`external-subagent profile show <name>`; an empty `profile list` result
+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
@@ -119,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/commands/tasks.mjs

@@ -499,6 +499,13 @@ export function parseProfileArgs(args) {
   throw new CliError('INVALID_ARGUMENT', `unsupported profile operation: ${operation}`, 2);
 }
 
+// Attached to `profile list` only when no usable profile exists, so a fresh
+// installation sees the format reference instead of an unexplained empty list.
+const EMPTY_PROFILES_HINT = 'no profiles found; create one JSON file per profile in this directory, '
+  + 'e.g. {"name":"codex-yolo","subagent":"codex","model":"gpt-5","permission_mode":"yolo"}; '
+  + 'fields: name (required), subagent, model, effort, permission_mode (build|edit|plan|yolo), '
+  + 'developer_instructions; see the "Spawn profiles" section of README.md';
+
 export function profileCommand(paths, inputOrArgs, env = process.env) {
   const input = Array.isArray(inputOrArgs) ? parseProfileArgs(inputOrArgs) : inputOrArgs;
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -526,6 +533,7 @@ export function profileCommand(paths, inputOrArgs, env = process.env) {
         profiles: [],
         warnings: [],
         message: `profiles directory does not exist: ${dir}`,
+        hint: EMPTY_PROFILES_HINT,
       };
     }
     return {
@@ -533,6 +541,7 @@ export function profileCommand(paths, inputOrArgs, env = process.env) {
       directory: dir,
       profiles: scanned.availableNames,
       warnings: scanned.warnings.map((w) => ({ file: w.file, diagnostic: w.diagnostic })),
+      ...(scanned.availableNames.length === 0 ? { hint: EMPTY_PROFILES_HINT } : {}),
     };
   }
 

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.0';
+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,