external-subagent 0.4.1 → 0.5.0

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

package/cli/install/service-macos.mjs

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

package/cli/install/update.mjs

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