@polderlabs/bizar 5.4.0 → 5.5.0

package/cli/service-controller.mjs

@@ -40,6 +40,7 @@ import { homedir, platform } from 'node:os';
 import { join, dirname, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bizarConfigDir } from './utils.mjs';
+import { buildServiceEnvFile } from './service-env.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -101,6 +102,9 @@ function linuxUnitPath() {
 function linuxEnvPath() {
   return join(bizarConfigDir(), 'service.env');
 }
+function linuxHeadroomUnitPath() {
+  return join(userUnitDir(), 'bizar-headroom.service');
+}
 function darwinPlistPath() {
   return join(launchAgentsDir(), 'com.bizar.dashboard.plist');
 }
@@ -140,7 +144,13 @@ function linuxUnitContent({ nodePath, projectRoot }) {
   const cliEntry = join(projectRoot, 'cli', 'bin.mjs');
   return [
     '[Unit]',
-    'Description=Bizar background service daemon',
+    'Description=Bizar background service daemon (schedules + task-delegator)',
+    // v5.x — issue #7 — Make the service unit more robust.
+    // Bump StartLimitInterval so transient failures don't trip the
+    // systemd rate-limit (default 10s / 5 starts is too aggressive
+    // for a service that restarts after `bizar update`).
+    'StartLimitIntervalSec=300',
+    'StartLimitBurst=10',
     'After=network-online.target',
     'Wants=network-online.target',
     '',
@@ -148,9 +158,15 @@ function linuxUnitContent({ nodePath, projectRoot }) {
     'Type=simple',
     `EnvironmentFile=${envPath}`,
     `ExecStart=${nodePath} ${cliEntry} service _daemon`,
-    'Restart=always',
+    // Restart=on-failure means we only auto-restart on actual errors
+    // (non-zero exit). The default `always` would also restart on
+    // SIGTERM (which the user just used to stop us), making manual
+    // `systemctl --user stop` a fight against the supervisor.
+    'Restart=on-failure',
     'RestartSec=5',
     'TimeoutStopSec=20',
+    // Hard ceiling so a runaway daemon doesn't pin a CPU forever.
+    'CPUQuota=10%',
     '',
     '[Install]',
     'WantedBy=default.target',
@@ -159,21 +175,163 @@ function linuxUnitContent({ nodePath, projectRoot }) {
 }
 
 function linuxEnvFileContent({ projectRoot }) {
-  const lines = [
-    `# Generated by bizar service install — do not edit by hand.`,
-    `# Source this file from your shell to get the same env that the daemon sees.`,
-    `BIZAR_HOME=${bizarConfigDir()}`,
-    `PATH=${process.env.PATH || '/usr/local/bin:/usr/bin:/bin'}`,
-    `BIZAR_REPO=${projectRoot}`,
-  ];
-  // Secrets are NOT written here. A user can append OPENCODE_SERVER_PASSWORD
-  // manually, but the controller never copies secrets into the unit file.
-  if (process.env.OPENCODE_SERVER_PASSWORD && !process.env.BIZAR_REDACT_PASSWORD) {
-    // Honored only if the user opts in via BIZAR_REDACT_PASSWORD=1 — default
-    // is to never persist secrets; the comment above documents this.
-    lines.push(`OPENCODE_SERVER_PASSWORD=${process.env.OPENCODE_SERVER_PASSWORD}`);
+  return buildServiceEnvFile({ bizarHome: bizarConfigDir(), repoPath: projectRoot });
+}
+
+// ── Headroom companion service (Linux) ─────────────────────────────────────────
+
+function linuxHeadroomUnitContent() {
+  const envPath = join(bizarConfigDir(), 'service.env');
+  return [
+    '[Unit]',
+    'Description=Bizar Headroom context-compression proxy',
+    'After=bizar.service',
+    'Wants=bizar.service',
+    '',
+    '[Service]',
+    'Type=simple',
+    `EnvironmentFile=${envPath}`,
+    'ExecStart=/bin/sh -c "command -v headroom >/dev/null 2>&1 && headroom proxy opencode || exit 0"',
+    'Restart=on-failure',
+    'RestartSec=10',
+    'TimeoutStopSec=15',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+function darwinHeadroomPlistPath() {
+  return join(launchAgentsDir(), 'com.bizar.headroom.plist');
+}
+
+function darwinHeadroomPlistContent({ nodePath, projectRoot }) {
+  const envContent = buildServiceEnvFile({ bizarHome: bizarConfigDir(), repoPath: projectRoot });
+  const envVars = parseEnvFile(envContent);
+  const envXml = envVars
+    .map(([k, v]) => `      <key>${xmlEscape(k)}</key>\n      <string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    '  <string>com.bizar.headroom</string>',
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    `    <string>${xmlEscape(nodePath)}</string>`,
+    '    <string>-c</string>',
+    '    <string>command -v headroom >/dev/null 2>&1 && headroom proxy opencode || exit 0</string>',
+    '  </array>',
+    '  <key>EnvironmentVariables</key>',
+    '  <dict>',
+    envXml,
+    '  </dict>',
+    '  <key>KeepAlive</key>',
+    '  <true/>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>StandardOutPath</key>',
+    `  <string>${xmlEscape(join(bizarConfigDir(), 'headroom.log'))}</string>`,
+    '  <key>StandardErrorPath</key>',
+    `  <string>${xmlEscape(join(bizarConfigDir(), 'headroom.log'))}</string>`,
+    '  <key>WorkingDirectory</key>',
+    `  <string>${xmlEscape(projectRoot)}</string>`,
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+function installHeadroomServiceLinux({ force = false }) {
+  // Honour BIZAR_HEADROOM_AUTOSTART from process.env (already merged by buildServiceEnvFile)
+  const headroomAutoStart = process.env.BIZAR_HEADROOM_AUTOSTART !== '0';
+  if (!headroomAutoStart) {
+    return ok({ note: 'headroom autostart disabled via BIZAR_HEADROOM_AUTOSTART=0' });
+  }
+  if (!existsSync(userUnitDir())) {
+    try { mkdirSync(userUnitDir(), { recursive: true }); } catch (err) {
+      return fail(`cannot create ${userUnitDir()}: ${err.message}`);
+    }
+  }
+  const unitPath = linuxHeadroomUnitPath();
+  const want = linuxHeadroomUnitContent();
+  if (!force && existsSync(unitPath)) {
+    const have = readFileSync(unitPath, 'utf8').trim() + '\n';
+    if (have === want.trim() + '\n') {
+      return ok({ alreadyInstalled: true, unitPath, note: 'headroom unit already matches' });
+    }
+  }
+  try {
+    writeFileSync(unitPath, want, { encoding: 'utf8', mode: 0o644 });
+  } catch (err) {
+    return fail(`write ${unitPath}: ${err.message}`);
+  }
+  runCmd('systemctl', ['--user', 'daemon-reload']);
+  const r = runCmd('systemctl', ['--user', 'enable', '--now', 'bizar-headroom.service']);
+  if (r.error || (r.status !== 0 && r.status !== null)) {
+    return fail(`headroom service enable failed: ${r.stderr || r.error?.message || `exit ${r.status}`}`, { unitPath });
   }
-  return lines.join('\n') + '\n';
+  return ok({ unitPath, note: 'headroom companion service installed and started' });
+}
+
+function uninstallHeadroomServiceLinux() {
+  const unitPath = linuxHeadroomUnitPath();
+  if (!existsSync(unitPath)) {
+    return ok({ unitPath: null, note: 'no headroom systemd unit installed' });
+  }
+  runCmd('systemctl', ['--user', 'disable', '--now', 'bizar-headroom.service']);
+  try { unlinkSync(unitPath); } catch { /* ignore */ }
+  runCmd('systemctl', ['--user', 'daemon-reload']);
+  return ok({ unitPath: null, note: 'headroom systemd unit removed' });
+}
+
+function installHeadroomServiceDarwin({ nodePath, projectRoot, force = false }) {
+  const headroomAutoStart = process.env.BIZAR_HEADROOM_AUTOSTART !== '0';
+  if (!headroomAutoStart) {
+    return ok({ note: 'headroom autostart disabled via BIZAR_HEADROOM_AUTOSTART=0' });
+  }
+  const dir = launchAgentsDir();
+  if (!existsSync(dir)) {
+    try { mkdirSync(dir, { recursive: true }); } catch (err) {
+      return fail(`cannot create ${dir}: ${err.message}`);
+    }
+  }
+  const plistPath = darwinHeadroomPlistPath();
+  const want = darwinHeadroomPlistContent({ nodePath, projectRoot });
+  if (!force && existsSync(plistPath)) {
+    const have = readFileSync(plistPath, 'utf8').trim() + '\n';
+    if (have === want.trim() + '\n') {
+      const lst = runCmd('launchctl', ['list']);
+      if (lst.status === 0 && /com\.bizar\.headroom/.test(lst.stdout)) {
+        return ok({ alreadyInstalled: true, unitPath: plistPath, note: 'headroom plist matches and is loaded' });
+      }
+    }
+  }
+  try {
+    writeFileSync(plistPath, want, { encoding: 'utf8', mode: 0o644 });
+    try { chmodSync(plistPath, 0o644); } catch { /* best-effort */ }
+  } catch (err) {
+    return fail(`write ${plistPath}: ${err.message}`);
+  }
+  runCmd('launchctl', ['unload', plistPath]);
+  const load = runCmd('launchctl', ['load', '-w', plistPath]);
+  if (load.error || (load.status !== 0 && load.status !== null)) {
+    return fail(`launchctl load failed for headroom: ${load.stderr || load.error?.message || `exit ${load.status}`}`, { unitPath: plistPath });
+  }
+  return ok({ unitPath: plistPath, note: 'headroom companion plist installed and loaded' });
+}
+
+function uninstallHeadroomServiceDarwin() {
+  const plistPath = darwinHeadroomPlistPath();
+  if (!existsSync(plistPath)) {
+    return ok({ unitPath: null, note: 'no headroom launchd plist installed' });
+  }
+  runCmd('launchctl', ['unload', plistPath]);
+  try { unlinkSync(plistPath); } catch { /* ignore */ }
+  return ok({ unitPath: null, note: 'headroom launchd plist removed' });
 }
 
 function installServiceLinux({ nodePath, projectRoot, force = false }) {
@@ -235,6 +393,13 @@ function installServiceLinux({ nodePath, projectRoot, force = false }) {
     return fail(`systemctl --user enable --now failed: ${r.stderr || r.error?.message || `exit ${r.status}`}`, { unitPath });
   }
 
+  // Also install headroom companion service (non-fatal if it fails)
+  const hr = installHeadroomServiceLinux({ force });
+  if (!hr.ok) {
+    // Non-fatal: headroom is optional
+    console.log(`  ${hr.error || 'headroom companion install failed'}`);
+  }
+
   return ok({
     unitPath,
     note: 'systemd user unit installed and started (or already running)',
@@ -261,6 +426,14 @@ function uninstallServiceLinux() {
   });
 }
 
+function stopServiceLinux() {
+  const r = runCmd('systemctl', ['--user', 'stop', 'bizar.service']);
+  if (r.error || (r.status !== 0 && r.status !== null)) {
+    return { ok: false, error: `systemctl stop failed: ${r.stderr || r.error?.message || `exit ${r.status}`}` };
+  }
+  return { ok: true, note: 'bizar.service stopped' };
+}
+
 function linuxServiceStatus() {
   const unitPath = linuxUnitPath();
   if (!existsSync(unitPath)) {
@@ -277,11 +450,9 @@ function linuxServiceStatus() {
 
 function darwinPlistContent({ nodePath, projectRoot }) {
   const cliEntry = join(projectRoot, 'cli', 'bin.mjs');
-  const envVars = [
-    ['BIZAR_HOME', bizarConfigDir()],
-    ['PATH', process.env.PATH || '/usr/local/bin:/usr/bin:/bin'],
-    ['BIZAR_REPO', projectRoot],
-  ];
+  // Use buildServiceEnvFile to get all env vars (honours existing process.env)
+  const envContent = buildServiceEnvFile({ bizarHome: bizarConfigDir(), repoPath: projectRoot });
+  const envVars = parseEnvFile(envContent);
   const envXml = envVars
     .map(([k, v]) => `      <key>${xmlEscape(k)}</key>\n      <string>${xmlEscape(v)}</string>`)
     .join('\n');
@@ -326,6 +497,25 @@ function xmlEscape(s) {
     .replace(/>/g, '&gt;');
 }
 
+/**
+ * Parse a shell-style env file (KEY=VALUE lines, # comments) into
+ * an array of [key, value] tuples. Used by darwinPlistContent to
+ * embed all env vars in the launchd plist.
+ */
+function parseEnvFile(content) {
+  const result = [];
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx < 0) continue;
+    const key = trimmed.slice(0, eqIdx);
+    const value = trimmed.slice(eqIdx + 1);
+    result.push([key, value]);
+  }
+  return result;
+}
+
 function installServiceDarwin({ nodePath, projectRoot, force = false }) {
   const dir = launchAgentsDir();
   if (!existsSync(dir)) {
@@ -371,6 +561,13 @@ function installServiceDarwin({ nodePath, projectRoot, force = false }) {
   if (load.error || (load.status !== 0 && load.status !== null)) {
     return fail(`launchctl load failed: ${load.stderr || load.error?.message || `exit ${load.status}`}`, { unitPath: plistPath });
   }
+
+  // Also install headroom companion service (non-fatal if it fails)
+  const hr = installHeadroomServiceDarwin({ nodePath, projectRoot, force });
+  if (!hr.ok) {
+    console.log(`  ${hr.error || 'headroom companion install failed'}`);
+  }
+
   return ok({ unitPath: plistPath, note: 'plist installed and loaded' });
 }
 
@@ -389,6 +586,15 @@ function uninstallServiceDarwin() {
   return ok({ unitPath: null, note: 'plist removed' });
 }
 
+function stopServiceDarwin() {
+  const plistPath = darwinPlistPath();
+  const r = runCmd('launchctl', ['unload', plistPath]);
+  if (r.error || (r.status !== 0 && r.status !== null)) {
+    return { ok: false, error: `launchctl unload failed: ${r.stderr || r.error?.message || `exit ${r.status}`}` };
+  }
+  return { ok: true, note: 'com.bizar.dashboard stopped' };
+}
+
 function darwinServiceStatus() {
   const plistPath = darwinPlistPath();
   const lst = runCmd('launchctl', ['list']);
@@ -404,12 +610,22 @@ function darwinServiceStatus() {
 
 function windowsCmdContent({ nodePath, projectRoot }) {
   const cliEntry = join(projectRoot, 'cli', 'bin.mjs');
+  const envContent = buildServiceEnvFile({ bizarHome: bizarConfigDir(), repoPath: projectRoot });
+  const envLines = [];
+  for (const line of envContent.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx < 0) continue;
+    const key = trimmed.slice(0, eqIdx);
+    const value = trimmed.slice(eqIdx + 1);
+    envLines.push(`set "${key}=${value.replace(/"/g, '\\"')}"`);
+  }
   const lines = [
     '@echo off',
     'REM Generated by bizar service install — do not edit by hand.',
-    `set "BIZAR_HOME=${bizarConfigDir()}"`,
-    `set "PATH=${process.env.PATH || '%PATH%'}"`,
-    `:loop`,
+    ...envLines,
+    ':loop',
     `node "${cliEntry}" service _daemon`,
     'REM Restart with 5s backoff on exit. /b keeps this window alive.',
     'timeout /t 5 /nobreak >nul',
@@ -481,6 +697,15 @@ function uninstallServiceWindows() {
   });
 }
 
+function stopServiceWindows() {
+  const taskName = 'BizarDashboardService';
+  const r = runCmd('cmd.exe', ['/c', 'schtasks', '/End', '/TN', taskName]);
+  if (r.error || (r.status !== 0 && r.status !== null)) {
+    return { ok: false, error: `schtasks /End failed: ${r.stderr || r.error?.message || `exit ${r.status}`}` };
+  }
+  return { ok: true, note: 'BizarDashboardService stopped' };
+}
+
 function isScheduledTaskInstalled(taskName) {
   // schtasks /Query is silent on stdout when the task is missing.
   const r = runCmd('cmd.exe', ['/c', 'schtasks', '/Query', '/TN', taskName], { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -525,10 +750,128 @@ export function installService(opts = {}) {
 }
 
 export function uninstallService() {
-  if (PLATFORM === 'linux') return uninstallServiceLinux();
-  if (PLATFORM === 'darwin') return uninstallServiceDarwin();
-  if (PLATFORM === 'win32') return uninstallServiceWindows();
-  return fail(`unsupported platform: ${PLATFORM}`);
+  let result;
+  if (PLATFORM === 'linux') result = uninstallServiceLinux();
+  else if (PLATFORM === 'darwin') result = uninstallServiceDarwin();
+  else if (PLATFORM === 'win32') result = uninstallServiceWindows();
+  else return fail(`unsupported platform: ${PLATFORM}`);
+  // Also uninstall headroom companion
+  if (PLATFORM === 'linux') uninstallHeadroomServiceLinux();
+  if (PLATFORM === 'darwin') uninstallHeadroomServiceDarwin();
+  return result;
+}
+
+/**
+ * Install the headroom companion service only (does NOT install the
+ * main dashboard service). Idempotent. Safe to re-run.
+ */
+export function installHeadroomService(opts = {}) {
+  const nodePath = resolveNodePath(opts.nodePath);
+  const projectRoot = resolveRepoRoot(opts.projectRoot);
+  if (PLATFORM === 'linux') return installHeadroomServiceLinux({ force: !!opts.force });
+  if (PLATFORM === 'darwin') return installHeadroomServiceDarwin({ nodePath, projectRoot, force: !!opts.force });
+  return ok({ note: `headroom companion not supported on ${PLATFORM}` });
+}
+
+export function uninstallHeadroomService() {
+  if (PLATFORM === 'linux') return uninstallHeadroomServiceLinux();
+  if (PLATFORM === 'darwin') return uninstallHeadroomServiceDarwin();
+  return ok({ note: `headroom companion not supported on ${PLATFORM}` });
+}
+
+/**
+ * v5.x — Restart the service (issue #7).
+ *
+ * The update flow replaces the on-disk files that the running service is
+ * holding open. Without a stop/start cycle, the service either crashes
+ * when the underlying inode is replaced (Linux) or runs forever against a
+ * stale binary (macOS / Windows).
+ *
+ * This function:
+ *   1. Stops the running service (systemctl stop / launchctl unload /
+ *      schtasks /End). Best-effort — if the service isn't running, we
+ *      treat that as success and continue.
+ *   2. Waits up to `waitMs` (default 10s) for the service to exit.
+ *   3. Re-installs the unit file. Idempotent — if the content hasn't
+ *      changed, installService returns alreadyInstalled=true.
+ *   4. Starts the service again (systemctl --user enable --now / launchctl
+ *      load -w / schtasks /Run).
+ *
+ * Returns a structured { ok, stopped, installed, started, error? }.
+ *
+ * @param {{ nodePath?: string, projectRoot?: string, force?: boolean, waitMs?: number, timeoutMs?: number, dryRun?: boolean }} [opts]
+ */
+export function restartService(opts = {}) {
+  const { waitMs = 10_000, dryRun = false } = opts;
+  const nodePath = resolveNodePath(opts.nodePath);
+  const projectRoot = resolveRepoRoot(opts.projectRoot);
+  const force = !!opts.force;
+
+  if (dryRun) {
+    return ok({
+      stopped: true,
+      installed: { alreadyInstalled: true },
+      started: true,
+      note: 'dry-run: would stop, reinstall, and start the service',
+    });
+  }
+
+  // 1. Stop (best-effort)
+  let stopped;
+  try {
+    if (PLATFORM === 'linux') stopped = stopServiceLinux();
+    else if (PLATFORM === 'darwin') stopped = stopServiceDarwin();
+    else if (PLATFORM === 'win32') stopped = stopServiceWindows();
+    else return fail(`unsupported platform: ${PLATFORM}`);
+  } catch (err) {
+    return fail(`stop failed: ${err.message}`, { stopped: { ok: false, error: err.message } });
+  }
+
+  // 2. Wait for the service to actually exit. The stop shell-outs are
+  //    synchronous in the per-platform functions (systemctl blocks until
+  //    stop completes; launchctl unload returns immediately; schtasks
+  //    /End returns immediately), so we additionally check the running
+  //    state and wait until the OS reports not-running OR our deadline
+  //    elapses.
+  const deadline = Date.now() + waitMs;
+  if (PLATFORM === 'linux' || PLATFORM === 'darwin' || PLATFORM === 'win32') {
+    while (Date.now() < deadline) {
+      const st = serviceStatus();
+      if (!st.running) break;
+      // Synchronous short sleep — service should exit in <2s on a
+      // healthy system. We avoid pulling in a timer just for this
+      // bounded wait.
+      const until = Date.now() + 200;
+      while (Date.now() < until) { /* spin briefly */ }
+    }
+  }
+
+  // 3. Reinstall
+  let installed;
+  try {
+    installed = installService({ nodePath, projectRoot, force });
+  } catch (err) {
+    return fail(`reinstall failed: ${err.message}`, { stopped, installed: { ok: false, error: err.message } });
+  }
+  if (!installed.ok) {
+    return fail(`reinstall failed: ${installed.error}`, { stopped, installed });
+  }
+
+  // 4. Start. The installService* helpers above already do an
+  //    `enable --now` / `load -w` / `schtasks /Create` (the Windows
+  //    wrapper script contains a self-restart loop, so creating the
+  //    task starts the daemon). So when installService succeeds, the
+  //    service is already running on every platform. Surface that as
+  //    `started: true` here. The Status field of the return value is
+  //    still authoritative — operators can call `bizar service status`
+  //    to confirm.
+  return ok({
+    stopped,
+    installed,
+    started: true,
+    unitPath: installed.unitPath || serviceUnitPath({ projectRoot }),
+    note: 'service stopped, unit reinstalled, service started',
+  });
 }
 
 export function isInstalled() {
@@ -559,6 +902,12 @@ if (isMain) {
     console.log(fmt(installService({ force, dryRun: dry })));
   } else if (sub === 'uninstall') {
     console.log(fmt(uninstallService()));
+  } else if (sub === 'restart') {
+    // v5.x — issue #7. Stop → reinstall unit → start. Idempotent on the
+    // install step (when the unit content hasn't changed, the second
+    // installService call returns alreadyInstalled=true and the service
+    // is still restarted).
+    console.log(fmt(restartService({ force, dryRun: dry })));
   } else if (sub === 'status') {
     console.log(fmt(serviceStatus()));
   } else if (sub === 'is-installed') {
@@ -570,6 +919,7 @@ service-controller — platform-aware installer for the Bizar background service
 Usage:
   node cli/service-controller.mjs install [--force] [--dry-run]
   node cli/service-controller.mjs uninstall
+  node cli/service-controller.mjs restart [--force] [--dry-run]
   node cli/service-controller.mjs status
   node cli/service-controller.mjs is-installed
 `);

package/cli/service-controller.test.mjs

@@ -2,6 +2,7 @@
  * cli/service-controller.test.mjs
  *
  * v4.4.0 — Smoke tests for the platform-aware service installer.
+ * v5.x — Adds tests for the `restartService()` lifecycle (issue #7).
  *
  * Strategy: focus on the parts that are platform-portable and don't
  * require touching the user's real `$XDG_CONFIG_HOME/systemd/`:
@@ -10,6 +11,8 @@
  *   - `installService({ dryRun: true })` is side-effect free
  *   - `installService()` is idempotent (run twice → second reports
  *     `alreadyInstalled: true`)
+ *   - `restartService({ dryRun: true })` is side-effect free
+ *   - `restartService({ dryRun: true })` returns the documented shape
  *
  * Tests that actually install / uninstall on the host machine are
  * skipped by default — opt in by setting `BIZAR_TEST_INSTALL=1`.
@@ -23,6 +26,7 @@ import { join } from 'node:path';
 import {
   installService,
   uninstallService,
+  restartService,
   serviceStatus,
   serviceUnitPath,
 } from './service-controller.mjs';
@@ -90,3 +94,99 @@ test('file permissions on the env file are 0600 (Linux/macOS only)', { skip: HOS
   }
   uninstallService();
 });
+
+// ── v5.x — restartService lifecycle (issue #7) ──────────────────────────────
+
+test('restartService({ dryRun: true }) makes no filesystem changes', () => {
+  const before = serviceStatus();
+  const r = restartService({ dryRun: true });
+  assert.equal(r.ok, true, `dry-run restart returned ok=false: ${r.error}`);
+  const after = serviceStatus();
+  // dry-run must not flip the installed bit.
+  assert.equal(before.installed, after.installed);
+  assert.equal(before.running, after.running);
+});
+
+test('restartService({ dryRun: true }) returns the documented shape', () => {
+  const r = restartService({ dryRun: true });
+  assert.equal(r.ok, true);
+  assert.equal(r.started, true, 'dry-run reports started=true');
+  // stopped/installed are present (even if their inner shape is
+  // minimal in dry-run mode).
+  assert.ok('stopped' in r, 'stopped field present');
+  assert.ok('installed' in r, 'installed field present');
+});
+
+test('restartService() on a fresh install (host-only)', { skip: !ALLOW_INSTALL }, () => {
+  // Tear down, install, then restart and confirm the unit path is
+  // reported. We don't assert that the service is running because
+  // the OS init system (systemd / launchd / schtasks) may not be
+  // active in the test environment.
+  uninstallService();
+  const r1 = installService({});
+  assert.equal(r1.ok, true, `install failed: ${r1.error}`);
+
+  const r2 = restartService({});
+  assert.equal(r2.ok, true, `restart failed: ${r2.error}`);
+  assert.ok(typeof r2.unitPath === 'string', 'unitPath reported');
+  assert.equal(r2.started, true, 'restart reports started=true');
+
+  // The service should still be reported as installed.
+  const status = serviceStatus();
+  assert.equal(status.installed, true, 'service still installed after restart');
+
+  uninstallService();
+});
+
+// ── v5.x — buildServiceEnvFile + parseEnvFile ────────────────────────────────
+
+test('buildServiceEnvFile returns string with all required vars', async () => {
+  const { buildServiceEnvFile } = await import('./service-env.mjs');
+  const content = buildServiceEnvFile({ repoPath: '/test/repo' });
+  assert.ok(typeof content === 'string');
+  assert.ok(content.includes('BIZAR_HOME='), 'BIZAR_HOME present');
+  assert.ok(content.includes('BIZAR_REPO=/test/repo'), 'BIZAR_REPO present');
+  assert.ok(content.includes('PATH='), 'PATH present');
+  assert.ok(content.includes('OPENCODE_SERVER_PASSWORD='), 'OPENCODE_SERVER_PASSWORD present');
+  assert.ok(content.includes('BIZAR_DASHBOARD_PORT='), 'BIZAR_DASHBOARD_PORT present');
+  assert.ok(content.includes('BIZAR_DASHBOARD_HOST='), 'BIZAR_DASHBOARD_HOST present');
+  assert.ok(content.includes('BIZAR_LOG_LEVEL='), 'BIZAR_LOG_LEVEL present');
+  assert.ok(content.includes('BIZAR_HEADROOM_AUTOSTART='), 'BIZAR_HEADROOM_AUTOSTART present');
+  assert.ok(content.includes('BIZAR_LIGHTRAG_AUTOSTART='), 'BIZAR_LIGHTRAG_AUTOSTART present');
+  assert.ok(content.includes('BIZAR_MEMORY_VAULT='), 'BIZAR_MEMORY_VAULT present');
+});
+
+test('buildServiceEnvFile honours existing process.env values', async () => {
+  const { buildServiceEnvFile } = await import('./service-env.mjs');
+  const origPort = process.env.BIZAR_DASHBOARD_PORT;
+  process.env.BIZAR_DASHBOARD_PORT = '9999';
+  try {
+    const content = buildServiceEnvFile({ repoPath: '/test/repo' });
+    assert.ok(content.includes('BIZAR_DASHBOARD_PORT=9999'), 'honoured BIZAR_DASHBOARD_PORT from env');
+  } finally {
+    if (origPort !== undefined) process.env.BIZAR_DASHBOARD_PORT = origPort;
+    else delete process.env.BIZAR_DASHBOARD_PORT;
+  }
+});
+
+test('buildServiceEnvFile uses default BIZAR_MEMORY_VAULT when not set', async () => {
+  const { buildServiceEnvFile } = await import('./service-env.mjs');
+  const orig = process.env.BIZAR_MEMORY_VAULT;
+  delete process.env.BIZAR_MEMORY_VAULT;
+  try {
+    const content = buildServiceEnvFile({ repoPath: '/test/repo' });
+    assert.ok(content.includes('BIZAR_MEMORY_VAULT='), 'BIZAR_MEMORY_VAULT present');
+    assert.ok(content.includes('.bizar_memory'), 'default vault path present');
+  } finally {
+    if (orig !== undefined) process.env.BIZAR_MEMORY_VAULT = orig;
+  }
+});
+
+test('darwinPlistContent generates XML with BIZAR env vars (dry-run only — no file written)', async () => {
+  // dry-run test: verify darwinPlistContent is accessible and produces XML.
+  // We test via installService({ dryRun: true }) which uses darwinPlistContent.
+  const r = installService({ dryRun: true });
+  assert.equal(r.ok, true);
+  assert.ok(typeof r.note === 'string');
+});
+