external-subagent 0.4.0 → 0.5.0

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;
+}

package/cli/install/service-activation.mjs

@@ -4,7 +4,9 @@ import { atomicWrite } from '../fs-atomic.mjs';
 import { CliError } from '../errors.mjs';
 import { callDaemon } from '../rpc.mjs';
 import { LAUNCH_AGENT_LABEL } from '../constants.mjs';
+import { platform } from '../paths.mjs';
 import { launchAgentPlist, launchctl } from './service-macos.mjs';
+import { SYSTEMD_UNIT_NAME, execStartProgram, replaceExecStartProgram, systemctl, systemdUnit, unitServiceStatus } from './service-linux.mjs';
 
 const xml = (s) => s.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 const unxml = (s) => s.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&');
@@ -15,12 +17,18 @@ export function hasInstalledService(paths) {
   return Boolean(paths.launchAgent && fs.existsSync(paths.launchAgent));
 }
 
+// Platform dispatch (S03): the same activation health/rollback contract runs
+// over launchd on macOS (verbatim) and the systemd user manager on Linux.
+export async function activateService(paths, candidate, options = {}) {
+  return platform() === 'darwin' ? activateLaunchdService(paths, candidate, options) : activateSystemdService(paths, candidate, options);
+}
+
 // The service definition is derived from the CURRENT config: activation
 // regenerates the whole plist (environment, revision, runtime forwarding) so a
 // reconfigured installation can never keep serving stale launchd environment.
 // Only rollback restores the previous definition bytes — the exact known state
 // the service ran before — with its executable repointed.
-export async function activateService(paths, candidate, options = {}) {
+async function activateLaunchdService(paths, candidate, options = {}) {
   const control = options.launchctl || launchctl;
   const rpc = options.callDaemon || callDaemon;
   const target = `gui/${process.getuid()}/${LAUNCH_AGENT_LABEL}`;
@@ -138,3 +146,127 @@ export async function activateService(paths, candidate, options = {}) {
     throw error;
   }
 }
+
+// The systemd twin of the launchd activation above: same drain/claim prelude,
+// same health verification (a NEW process running the selected artifact's
+// exact bytes and self-reporting its identity), same rollback-to-retained-bytes
+// contract.  unload = disable --now + the bounded inactive confirmation;
+// load = daemon-reload + enable --now (the same bootstrap init uses).
+async function activateSystemdService(paths, candidate, options = {}) {
+  const control = options.systemctl || systemctl;
+  const rpc = options.callDaemon || callDaemon;
+  const oldUnit = fs.readFileSync(paths.launchAgent);
+  const oldPath = execStartProgram(oldUnit);
+  if (!oldPath) throw new CliError('SERVICE_DEFINITION_INVALID', 'installed service has no executable entry');
+  const servicePid = async () => {
+    const view = unitServiceStatus(control);
+    if (view.skipped) throw new CliError('SERVICE_NOT_VERIFIED', 'service control was skipped');
+    if (!view.registered) return null;
+    return view.pid;
+  };
+  const oldPid = await servicePid();
+  const oldStatus = oldPid ? await rpc(paths.socket, 'status', {}) : null;
+  // The running daemon's self-reported digest is the truth about which bytes
+  // the service was executing; the file at oldPath may already carry the NEXT
+  // version after an npm install replaced the package directory in place.
+  const runningArtifact = oldStatus?.identity?.daemon?.artifact;
+  const oldSha = (typeof runningArtifact?.sha256 === 'string' && runningArtifact.sha256) || digest(oldPath);
+  if (oldPid) {
+    const drain = await rpc(paths.socket, 'drain-status', {});
+    if (!drain.ready_for_activation) throw new CliError('DAEMON_NOT_DRAINED', 'daemon still owns active or unreaped work');
+    const claim = await rpc(paths.socket, 'activate-ready', {});
+    if (!claim.activation_claim) throw new CliError('ACTIVATION_NOT_CLAIMED', 'daemon did not grant activation');
+  }
+  // npm may have replaced the old program path with the new payload: rolling
+  // the service back must run the OLD bytes, from the original path when they
+  // are still intact or from the retained payload copy the updater staged
+  // for exactly this recovery.
+  const rollbackExecutable = () => {
+    if (fs.existsSync(oldPath) && digest(oldPath) === oldSha) return { path: oldPath, sha256: oldSha };
+    const retained = options.rollbackPayload;
+    if (retained && typeof retained.path === 'string' && typeof retained.sha256 === 'string'
+      && fs.existsSync(retained.path) && digest(retained.path) === retained.sha256) {
+      return { path: retained.path, sha256: retained.sha256 };
+    }
+    throw new CliError('ROLLBACK_PAYLOAD_UNAVAILABLE', 'previous payload bytes are unavailable; automatic rollback refused');
+  };
+  const healthy = async (expected, previousPid, previousGeneration) => {
+    const deadline = Date.now() + (options.healthTimeoutMs ?? 10_000);
+    let last;
+    do {
+      try {
+        const pid = await servicePid();
+        if (!pid || pid === previousPid) throw new Error('service has no new process');
+        const status = await rpc(paths.socket, 'status', {});
+        const identity = status.identity?.daemon;
+        // Health verification uses the service generation and the running
+        // artifact identity. The diagnostic-only mcp_version never gates
+        // admission.
+        if (!status.service_generation || status.service_generation === previousGeneration
+          || identity?.artifact?.path !== expected.path || identity?.artifact?.sha256 !== expected.sha256
+          || (expected.version && identity?.version !== expected.version)) throw new Error('running daemon identity does not match selected payload');
+        if (await servicePid() !== pid) throw new Error('service process changed during health verification');
+        return { pid, version: identity.version, artifact: identity.artifact, service_generation: status.service_generation };
+      } catch (error) { last = error; }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    } while (Date.now() < deadline);
+    throw new CliError('SERVICE_HEALTH_FAILED', last?.message || 'service did not become healthy');
+  };
+  const unload = async () => {
+    const view = unitServiceStatus(control);
+    if (view.skipped || !view.registered) return;
+    await control(['disable', '--now', SYSTEMD_UNIT_NAME]);
+    const deadline = Date.now() + (options.unloadTimeoutMs ?? 10_000);
+    do {
+      const probe = unitServiceStatus(control);
+      if (probe.skipped || !probe.registered || (probe.state === 'inactive' && probe.pid === null)) return;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    } while (Date.now() < deadline);
+    throw new CliError('SERVICE_UNLOAD_TIMEOUT', 'systemd service remained active after disable --now');
+  };
+  const writeDefinition = (entryPath) => atomicWrite(paths.launchAgent, systemdUnit(paths, {
+    daemonPath: entryPath,
+    ...(options.zcodeRuntime !== undefined ? { zcodeRuntime: options.zcodeRuntime } : {}),
+  }), 0o600);
+  const restoreDefinition = (entryPath) => atomicWrite(paths.launchAgent, replaceExecStartProgram(oldUnit, entryPath), 0o600);
+  const load = async () => {
+    await control(['daemon-reload']);
+    await control(['enable', '--now', SYSTEMD_UNIT_NAME]);
+  };
+  const rollbackService = async () => {
+    await unload();
+    const previous = rollbackExecutable();
+    restoreDefinition(previous.path);
+    await load();
+    return healthy({ path: previous.path, sha256: previous.sha256, version: oldStatus?.identity?.daemon?.version }, oldPid, oldStatus?.service_generation);
+  };
+  try {
+    await unload();
+    writeDefinition(candidate.path);
+    await load();
+    const health = await healthy(candidate, oldPid, oldStatus?.service_generation);
+    return {
+      ...health,
+      rollback: async () => {
+        const restored = await rollbackService();
+        if (digest(oldPath) !== oldSha) return { ...restored, restored_from: 'retained_payload' };
+        return restored;
+      },
+    };
+  } catch (error) {
+    if (!oldPid) {
+      try {
+        await unload();
+        atomicWrite(paths.launchAgent, oldUnit, 0o600);
+        error.rollback = { attempted: true, restored: false, unit_restored: true, error: 'no previous service identity to verify' };
+      } catch (rollbackError) {
+        error.rollback = { attempted: true, restored: false, unit_restored: false, error: rollbackError.message };
+      }
+      throw error;
+    }
+    try {
+      error.rollback = await rollbackService();
+    } catch (rollbackError) { error.rollbackError = rollbackError.message; }
+    throw error;
+  }
+}

package/cli/install/service-linux.mjs

@@ -0,0 +1,327 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DAEMON_BIN_NAME, PRODUCT_NAME, zcodeRuntimePath } from '../constants.mjs';
+import { CliError } from '../errors.mjs';
+import { atomicWrite } from '../fs-atomic.mjs';
+import { nativeBinary } from './layout.mjs';
+import { systemdServicePath } from './path.mjs';
+import { readConfig } from '../config/read.mjs';
+
+// The one Linux service backend for the product daemon: a systemd USER unit,
+// never the system manager.  The unit pins absolute payload paths and a fixed
+// PATH so the user-manager environment never depends on the interactive shell,
+// exactly the contract the launchd plist owns on macOS (service-macos.mjs is
+// the structural twin; service-macos.mjs also performs the platform dispatch
+// between the two backends).  Bootstrap = daemon-reload + enable --now; bootout
+// = disable --now + a bounded inactive confirmation — the same idempotence and
+// removal-confirmation semantics, carried by `systemctl --user` and honoring
+// the EXTERNAL_SUBAGENT_TEST_NO_SYSTEMCTL seam (the structural twin of
+// EXTERNAL_SUBAGENT_TEST_NO_LAUNCHCTL) so fixture runs never touch the real
+// user manager.
+
+export const SYSTEMD_UNIT_NAME = `${PRODUCT_NAME}.service`;
+export const SYSTEMCTL_PATH = '/usr/bin/systemctl';
+
+// D-S04: a host without a reachable user manager gets an actionable
+// explanation, never an automatic `loginctl enable-linger` and never a detour
+// through the system manager.
+const NO_SESSION_HINT = 'log in through a real session (which provides $XDG_RUNTIME_DIR), or run \'loginctl enable-linger <user>\' so the user manager stays available without one; this product never enables linger, never modifies unrelated units, and never contacts the system (PID 1) manager';
+
+function noSessionError(detail = null) {
+  const cause = detail ?? 'neither $XDG_RUNTIME_DIR nor $DBUS_SESSION_BUS_ADDRESS is set';
+  return new CliError('NO_USER_SYSTEMD_SESSION', `systemctl --user cannot reach the systemd user manager: ${cause}. ${NO_SESSION_HINT}`);
+}
+
+export function hasUserSystemdSession(env = process.env) {
+  return Boolean(
+    (typeof env.XDG_RUNTIME_DIR === 'string' && env.XDG_RUNTIME_DIR !== '')
+      || (typeof env.DBUS_SESSION_BUS_ADDRESS === 'string' && env.DBUS_SESSION_BUS_ADDRESS !== ''),
+  );
+}
+
+// systemd's two expansion grammars differ, and both were verified against the
+// running user manager (systemd 259):
+//   Environment= values — NO variable expansion ("the '$' character has no
+//     special meaning", man systemd.exec; a literal `$HOME` is passed through
+//     verbatim), but %-specifier expansion IS performed (`%h` becomes the
+//     home directory; `%%` is a literal `%`).
+//   ExecStart arguments — BOTH expansions apply: `$`/`${}` at spawn time
+//     (`$$` passes a literal dollar, man systemd.service) and %-specifiers at
+//     load time (`%%` literal).
+// Each side therefore escapes only what its grammar consumes; both quote the
+// value with `\"`/`\\` per systemd.syntax (an unrecognized `\x` escape makes
+// systemd DROP the whole Environment assignment, so every backslash is
+// always doubled).  The `$`/`%` doublings use replacer functions because a
+// plain `'$$'` replacement string is itself a $-pattern ("insert one $") and
+// would silently cancel the escape.
+function escapeQuotedCharacters(value) {
+  return String(value)
+    .replaceAll('\\', () => '\\\\')
+    .replaceAll('"', () => '\\"');
+}
+
+function escapeEnvironmentValue(value) {
+  return escapeQuotedCharacters(value).replaceAll('%', () => '%%');
+}
+
+function escapeExecStartArgument(value) {
+  return escapeQuotedCharacters(value).replaceAll('$', () => '$$').replaceAll('%', () => '%%');
+}
+
+// A newline inside a unit directive cannot be escaped away: systemd ends the
+// assignment there and parses the remainder as NEW directive lines, so a
+// config value like "acp\nRestart=no\n#" silently overrides the product-fixed
+// Restart=always — and systemd-analyze verify accepts the corrupted unit
+// without a warning (reproduced with the real generator).  Both forwarding
+// paths therefore refuse such values loudly instead of writing a corrupted
+// unit; the macOS plist carries the same value as inert XML data and keeps
+// forwarding it (its generator is deliberately untouched).
+function assertUnitLineSafe(value, label) {
+  if (/[\n\r]/u.test(String(value))) {
+    throw new CliError('SERVICE_DEFINITION_INVALID',
+      `the ${label} contains a newline (line feed or carriage return); systemd unit directive lines cannot represent it, and the service definition is refused rather than written corrupted — remove the newline from the configuration value`);
+  }
+}
+
+function quotedArgument(value) {
+  assertUnitLineSafe(value, 'ExecStart argument');
+  return `"${escapeExecStartArgument(value)}"`;
+}
+
+// The assignment is quoted as a whole (`Environment="NAME=value"`): systemd
+// parses one assignment per line, and quotes around only the value would be
+// taken literally.
+function environmentLine(name, value) {
+  assertUnitLineSafe(value, `${name} environment value`);
+  return `Environment="${name}=${escapeEnvironmentValue(value)}"`;
+}
+
+function unescapeUnitValue(text) {
+  let out = '';
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '\\' && index + 1 < text.length) { out += text[index + 1]; index += 1; continue; }
+    if (char === '$' && text[index + 1] === '$') { out += '$'; index += 1; continue; }
+    if (char === '%' && text[index + 1] === '%') { out += '%'; index += 1; continue; }
+    out += char;
+  }
+  return out;
+}
+
+function firstExecStartToken(line) {
+  const rest = line.replace(/^[+!:-]+/u, ''); // systemd command prefixes (+, -, :, !, !!)
+  if (rest.startsWith('"')) {
+    for (let index = 1; index < rest.length; index += 1) {
+      if (rest[index] === '\\') { index += 1; continue; }
+      if (rest[index] === '"') return { token: rest.slice(1, index), after: rest.slice(index + 1) };
+    }
+    return null; // unterminated quote
+  }
+  const end = rest.search(/\s/u);
+  return { token: end === -1 ? rest : rest.slice(0, end), after: end === -1 ? '' : rest.slice(end) };
+}
+
+// The executable the unit pins — the systemd twin of the plist's first
+// ProgramArguments entry — used by activation to learn the old program and to
+// restore it byte-for-byte on rollback.
+export function execStartProgram(unitBytes) {
+  const match = unitBytes.toString('utf8').match(/^ExecStart=(.*)$/m);
+  if (!match) return null;
+  const token = firstExecStartToken(match[1]);
+  return token ? unescapeUnitValue(token.token) : null;
+}
+
+export function replaceExecStartProgram(unitBytes, program) {
+  const text = unitBytes.toString('utf8');
+  const match = text.match(/^ExecStart=(.*)$/m);
+  if (!match) return null;
+  const token = firstExecStartToken(match[1]);
+  if (!token) return null;
+  const prefix = match[1].match(/^[+!:-]*/u)[0];
+  const line = `ExecStart=${prefix}${quotedArgument(program)}${token.after}`;
+  // Replacer function: a raw replacement string would reinterpret $-patterns
+  // inside the restored unit text.
+  return Buffer.from(text.replace(/^ExecStart=.*$/m, () => line), 'utf8');
+}
+
+// The same parameterization the plist generator carries (one-to-one): the
+// verified daemon artifact, the data paths the daemon takes as arguments, the
+// pinned ZCode runtime forwarded exactly when that installation exists, and
+// the persisted subagent environment.  Restart=always mirrors KeepAlive;
+// WantedBy=default.target mirrors RunAtLoad.  The daemon's own
+// --diagnostic-log writer puts daemon-error.log under the XDG state log
+// directory; stdout/stderr stay with the user journal, the systemd-native
+// sink (StandardOutput=append: cannot represent paths containing spaces).
+export function systemdUnit(paths, options = {}) {
+  const daemon = options.daemonPath || nativeBinary(DAEMON_BIN_NAME);
+  const config = readConfig(paths.config);
+  const { runtime_path: dshRuntime, home: dshHome, profile: dshProfile, version: dshVersion } = config.subagents.dsh;
+  const { runtime_path: codexRuntime, home: codexHome } = config.subagents.codex;
+  const { runtime_path: agyRuntime } = config.subagents.agy;
+  const configRevision = config.revision;
+  const zcodeRuntime = options.zcodeRuntime ?? zcodeRuntimePath(paths.home);
+  const execStart = [
+    quotedArgument(daemon),
+    quotedArgument('--database'),
+    quotedArgument(paths.database),
+    quotedArgument('--socket'),
+    quotedArgument(paths.socket),
+    ...(fs.existsSync(zcodeRuntime) ? [quotedArgument('--runtime'), quotedArgument(zcodeRuntime)] : []),
+    quotedArgument('--diagnostic-log'),
+    quotedArgument(path.join(paths.logs, 'daemon-error.log')),
+  ].join(' ');
+  const environment = [
+    environmentLine('PATH', systemdServicePath()),
+    ...(configRevision === null ? [] : [environmentLine('EXTERNAL_SUBAGENT_CONFIG_REVISION', configRevision)]),
+    ...(dshRuntime ? [environmentLine('DSH_RUNTIME_PATH', dshRuntime)] : []),
+    ...(dshHome ? [environmentLine('DSH_HOME', dshHome)] : []),
+    ...(dshProfile ? [environmentLine('DSH_PROFILE', dshProfile)] : []),
+    ...(dshVersion ? [environmentLine('DSH_VERSION', dshVersion)] : []),
+    ...(codexRuntime ? [environmentLine('CODEX_RUNTIME_PATH', codexRuntime)] : []),
+    ...(codexHome ? [environmentLine('CODEX_HOME', codexHome)] : []),
+    ...(agyRuntime ? [environmentLine('AGY_RUNTIME_PATH', agyRuntime)] : []),
+  ];
+  return Buffer.from([
+    `# Managed by ${PRODUCT_NAME}; regenerate with 'external-subagent init'.`,
+    '[Unit]',
+    `Description=${PRODUCT_NAME} daemon`,
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${execStart}`,
+    ...environment,
+    'Restart=always',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n'), 'utf8');
+}
+
+export function installServiceUnit(paths, options = {}) {
+  const unit = options.unit || systemdUnit(paths);
+  atomicWrite(paths.launchAgent, unit, 0o600);
+  return { installed: true, path: paths.launchAgent, unit: SYSTEMD_UNIT_NAME };
+}
+
+export function systemctl(args) {
+  if (process.env.EXTERNAL_SUBAGENT_TEST_NO_SYSTEMCTL === '1') {
+    return { action: args[0], skipped: true, reason: 'systemd neutralized by test seam' };
+  }
+  if (!hasUserSystemdSession()) throw noSessionError();
+  const result = spawnSync(SYSTEMCTL_PATH, ['--user', ...args], { encoding: 'utf8' });
+  if (result.error) throw new CliError('DAEMON_CONTROL_FAILED', `systemctl is unavailable: ${result.error.message}`);
+  if (result.status !== 0 && /Failed to connect to (?:user scope )?bus/iu.test(result.stderr || '')) {
+    throw noSessionError((result.stderr || '').trim());
+  }
+  if (result.status !== 0) {
+    throw new CliError('DAEMON_CONTROL_FAILED', (result.stderr || result.stdout || `systemctl ${args[0]} failed`).trim());
+  }
+  return { action: args[0], status: result.status, stdout: result.stdout };
+}
+
+// The single `show`-shaped probe every decision below reuses — the structural
+// twin of the launchctl print/absent discriminator.  A unit the user manager
+// has loaded reports its real state (`failed` included), so a status view built
+// on it can never turn a crashed unit into "healthy".
+export function unitServiceStatus(control, unit = SYSTEMD_UNIT_NAME) {
+  const result = control(['show', unit]);
+  if (result.skipped) return { skipped: true, reason: result.reason };
+  const properties = Object.fromEntries(
+    (result.stdout || '').split('\n').filter((line) => /^[A-Za-z]+=/.test(line)).map((line) => {
+      const separator = line.indexOf('=');
+      return [line.slice(0, separator), line.slice(separator + 1)];
+    }),
+  );
+  const pid = Number(properties.MainPID);
+  return {
+    registered: properties.LoadState === 'loaded',
+    load_state: properties.LoadState ?? null,
+    state: properties.ActiveState ?? null,
+    sub_state: properties.SubState ?? null,
+    pid: Number.isInteger(pid) && pid > 0 ? pid : null,
+  };
+}
+
+// ActiveState values that mean "the service has a live process right now".
+const LIVE_STATES = new Set(['active', 'activating', 'reloading']);
+
+// Read-only registration view for `status`.  A missing user session degrades
+// into an explicit unavailable view (with the linger hint) instead of failing
+// the whole read-only command; every other control failure still surfaces.
+export function systemdServiceRegistrationStatus(options = {}) {
+  const control = options.systemctl || systemctl;
+  try {
+    const view = unitServiceStatus(control);
+    if (view.skipped) return { query: 'skipped', registered: null, reason: view.reason };
+    const { registered, state, sub_state: subState, pid } = view;
+    return registered ? { registered: true, state, sub_state: subState, pid } : { registered: false };
+  } catch (error) {
+    if (error.code === 'NO_USER_SYSTEMD_SESSION') {
+      return { query: 'unavailable', registered: null, reason: error.message };
+    }
+    throw error;
+  }
+}
+
+// systemd natively answers a repeat `enable --now` with success even on a
+// running unit, but the product keeps the launchd contract: an already-live
+// service is reported as already_loaded with its real state/pid and is never
+// disturbed, and an enable that loses a race to another starter is settled
+// through the same probe instead of surfacing a phantom failure.
+export function bootstrapServiceSystemd(paths, _uid, options = {}) {
+  const control = options.systemctl || systemctl;
+  const alreadyLoaded = (view) => ({
+    action: 'bootstrap', unit: SYSTEMD_UNIT_NAME, already_loaded: true,
+    state: view.state ?? null, pid: view.pid ?? null,
+  });
+  const isLive = (view) => !view.skipped && view.registered === true && LIVE_STATES.has(view.state);
+  const existing = unitServiceStatus(control);
+  if (isLive(existing)) return alreadyLoaded(existing);
+  try {
+    control(['daemon-reload']);
+    return { ...control(['enable', '--now', SYSTEMD_UNIT_NAME]), unit: SYSTEMD_UNIT_NAME };
+  } catch (error) {
+    const settled = unitServiceStatus(control);
+    if (isLive(settled)) return alreadyLoaded(settled);
+    throw error;
+  }
+}
+
+// A disable --now returns before the unit has necessarily finished its
+// teardown, and a start issued inside that window can race the still-running
+// stop job — the same observed hazard the launchd bootout confirmation loop
+// guards.  stop therefore confirms the unit is actually inactive (and its
+// process gone or the socket removed) before reporting success, bounded, and
+// a unit that was never loaded is an idempotent already_stopped.
+export function bootoutServiceSystemd(paths, _uid, options = {}) {
+  const control = options.systemctl || systemctl;
+  // A skipped probe (test seam) reads as not-registered, exactly like the
+  // launchd bootout owner treats a neutralized print: fixture stops are
+  // already_stopped, never a real disable.
+  const stopped = (view) => view.skipped || view.registered !== true
+    || (view.state === 'inactive' && view.pid === null);
+  const existing = unitServiceStatus(control);
+  if (stopped(existing)) return { action: 'bootout', unit: SYSTEMD_UNIT_NAME, already_stopped: true };
+  let result;
+  try {
+    result = control(['disable', '--now', SYSTEMD_UNIT_NAME]);
+  } catch (error) {
+    // A racing removal (another stop, or the user manager itself) may have
+    // taken the unit down between the probe and the disable; confirm before
+    // reporting failure, so a repeated stop stays idempotent.
+    const settled = unitServiceStatus(control);
+    if (stopped(settled)) return { action: 'bootout', unit: SYSTEMD_UNIT_NAME, already_stopped: true };
+    throw error;
+  }
+  const deadline = Date.now() + (options.unloadTimeoutMs ?? 10_000);
+  for (;;) {
+    const probe = unitServiceStatus(control);
+    if (stopped(probe)) {
+      return { ...result, unit: SYSTEMD_UNIT_NAME, removed: true, socket_removed: !fs.existsSync(paths.socket) };
+    }
+    if (Date.now() >= deadline) throw new CliError('SERVICE_UNLOAD_TIMEOUT', 'systemd service remained active after disable --now');
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+  }
+}