@myvillage/cli 2.13.1 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/agent-runtime/runner.js

@@ -24,10 +24,10 @@ import path from 'path';
 import { getConfig } from '../utils/config.js';
 import { getAccessToken, isTokenExpired } from '../utils/auth.js';
 import { refreshAccessToken } from '../utils/api.js';
-import { listLocalAgents, readAgentConfig, getAgentDir, writeAgentConfig } from '../utils/local-agent.js';
+import { listLocalAgents, readAgentConfig, getAgentDir } from '../utils/local-agent.js';
 import { startDaemon, stopDaemon, isDaemonRunning, getDaemonInfo } from './daemon.js';
 import { shipLogsOnce, forgetLogCursor } from './log-shipper.js';
-import { writeSyncedModel } from '../utils/agent-models.js';
+import { writePublishedAgentConfig, readSyncedVersion } from '../utils/agent-config-sync.js';
 
 const RUNNER_STATE_FILE = path.join(os.homedir(), '.myvillage', 'runner.json');
 const DEFAULT_HEARTBEAT_MS = 20_000;
@@ -128,20 +128,6 @@ async function request(networkBaseUrl, pathname, method, body, headers) {
 
 // ── Config sync (materialise an assigned agent from the control plane) ───────
 
-// Records which published config version this machine last wrote, so we only
-// re-write files when the definition actually changed.
-function syncedVersionPath(agentDir) {
-  return path.join(agentDir, '.config-version');
-}
-
-function readSyncedVersion(agentDir) {
-  try {
-    return Number(fs.readFileSync(syncedVersionPath(agentDir), 'utf8').trim()) || 0;
-  } catch {
-    return 0;
-  }
-}
-
 /**
  * Write an assigned agent's files from its published definition, creating the
  * agent directory if this machine has never run it. Returns true when the agent
@@ -167,53 +153,12 @@ async function syncAgentConfig(ctx, assignment) {
     log(`could not fetch config for ${name} (${res.status}) — leaving local files alone`);
     return exists;
   }
-  const c = res.json.data;
-
-  fs.mkdirSync(agentDir, { recursive: true });
-  if (typeof c.promptMd === 'string' && c.promptMd) {
-    fs.writeFileSync(path.join(agentDir, 'prompt.md'), c.promptMd);
-  }
-  if (typeof c.toolsYaml === 'string' && c.toolsYaml) {
-    fs.writeFileSync(path.join(agentDir, 'tools.yaml'), c.toolsYaml);
-  }
-
-  // The trained models this agent was given travel with its config.
-  if (c.models && typeof c.models === 'object') {
-    for (const [slug, entry] of Object.entries(c.models)) {
-      const result = writeSyncedModel(slug, entry);
-      if (result === 'written') log(`synced model ${slug} for ${name}`);
-      else if (result === 'kept-local') log(`kept this machine's own model ${slug} for ${name}`);
-      else if (result === 'invalid') log(`skipped model ${slug} for ${name}: its files didn't check out`);
-    }
+  const { models } = writePublishedAgentConfig(name, { ...res.json.data, version: configVersion });
+  for (const { slug, result } of models) {
+    if (result === 'written') log(`synced model ${slug} for ${name}`);
+    else if (result === 'kept-local') log(`kept this machine's own model ${slug} for ${name}`);
+    else if (result === 'invalid') log(`skipped model ${slug} for ${name}: its files didn't check out`);
   }
-
-  // Compose agent.config.yaml from server-known identity + published schedule
-  // and brain, preserving anything already set locally that the control plane
-  // does not own.
-  let existingCfg = {};
-  try { existingCfg = readAgentConfig(name) || {}; } catch { /* first sync */ }
-  const cfg = {
-    ...existingCfg,
-    name,
-    display_name: c.displayName || existingCfg.display_name || name,
-    description: c.description ?? existingCfg.description ?? '',
-    man: {
-      ...(existingCfg.man || {}),
-      agent_id: c.agentId,
-      ...(c.villageAgentId ? { village_agent_id: c.villageAgentId } : {}),
-      handle: c.handle || name,
-    },
-    ...(c.schedule ? { schedule: c.schedule } : {}),
-    ...(c.brain ? { brain: c.brain } : {}),
-  };
-  writeAgentConfig(name, cfg);
-
-  // Keep an empty .env so the daemon's loader and 0600 expectations hold, but
-  // never overwrite secrets a person put here.
-  const envPath = path.join(agentDir, '.env');
-  if (!fs.existsSync(envPath)) fs.writeFileSync(envPath, '', { mode: 0o600 });
-
-  fs.writeFileSync(syncedVersionPath(agentDir), String(configVersion));
   log(`synced ${name} config v${configVersion}${exists ? '' : ' (new on this machine)'}`);
   return true;
 }

package/src/commands/agent-local.js

@@ -15,6 +15,7 @@ import {
   listCommunities,
   getAgentActivity,
   listMyAgents,
+  getAgentPublishedConfig,
   listMyUnlinkedAgentProfiles,
   createVillageAgent as apiCreateVillageAgent,
   listAgentTasks,
@@ -45,6 +46,7 @@ import {
   readAgentLogs,
   getLogFilePath,
 } from '../utils/local-agent.js';
+import { writePublishedAgentConfig } from '../utils/agent-config-sync.js';
 import { scaffoldAgent, TOOL_CATALOG, resolveCatalogEntry } from '../utils/agent-scaffolder.js';
 import { loadAgentRecipe, listAgentRecipes } from '../utils/agent-recipes.js';
 import { formatLocalAgentList, formatLocalAgentStatus } from '../utils/formatters.js';
@@ -1315,12 +1317,12 @@ export async function agentRememberCommand(name, text, options = {}) {
 // already has the agent — this command scaffolds the missing local config
 // (~/.myvillage/agents/<handle>/) so `agent start` can launch the daemon.
 //
-// What pulls down: the network identity (id, handle, displayName) and a
-// link to the existing VillageAgent task queue.
-// What doesn't: custom prompt edits, tools.yaml customizations, and any
-// API keys. Those stay machine-local and you'll need to redo them if you
-// want an exact replica. The scaffold defaults are a reasonable starting
-// point that will boot.
+// What pulls down: the network identity (id, handle, displayName), a link to
+// the existing VillageAgent task queue, and — when the agent has a published
+// definition (Studio publishes on every save) — its prompt.md, tools.yaml,
+// schedule, model settings and trained models.
+// What doesn't: API keys and other .env secrets. Those stay machine-local.
+// An agent that was never published falls back to the scaffold defaults.
 
 async function fetchMyAgentByHandle(handle) {
   const result = await listMyAgents({ includeVillageAgent: true });
@@ -1365,8 +1367,17 @@ export async function agentPullCommand(handle, options = {}) {
     return;
   }
 
-  // Default scaffold: just the always-on MyVillage MCP tool. Users can add
-  // more via `agent add-tool` once they're up.
+  // The published definition, if there is one. A failure here is not fatal:
+  // the scaffold defaults still boot.
+  let published = null;
+  try {
+    const c = await getAgentPublishedConfig(profile.id);
+    if (c && c.version > 0) published = c;
+  } catch { /* fall back to defaults */ }
+
+  // Scaffold first so the directory has everything `start` expects (routines/,
+  // logs/, .env); the published definition is then written over the defaults.
+  // Default scaffold: just the always-on MyVillage MCP tool.
   const agentDir = getAgentDir(agentName);
   try {
     scaffoldAgent(agentDir, {
@@ -1394,6 +1405,16 @@ export async function agentPullCommand(handle, options = {}) {
   }
   writeAgentConfig(agentName, cfg);
 
+  let models = [];
+  if (published) {
+    try {
+      ({ models } = writePublishedAgentConfig(agentName, published));
+    } catch (err) {
+      spinner.warn(`Pulled ${handle}, but its saved setup couldn't be written: ${err.message}`);
+      published = null;
+    }
+  }
+
   spinner.succeed(`Pulled ${handle} to ~/.myvillage/agents/${agentName}/`);
 
   console.log('');
@@ -1404,11 +1425,25 @@ export async function agentPullCommand(handle, options = {}) {
   } else {
     console.log(`    - ${chalk.yellow('No VillageAgent shim found — one will be created on first start.')}`);
   }
-  console.log('');
-  console.log(brand.teal('  Defaults that may need tweaking:'));
-  console.log(`    - ${brand.gold('prompt.md')} (system prompt — generic template)`);
-  console.log(`    - ${brand.gold('tools.yaml')} (only the MyVillage tool is enabled)`);
-  console.log(`    - ${brand.gold('agent.config.yaml')} (anthropic + claude-sonnet by default)`);
+  if (published) {
+    const brain = published.brain;
+    console.log(`    - Saved setup v${published.version}: ${published.promptMd ? 'prompt.md, ' : ''}${published.toolsYaml ? 'tools.yaml, ' : ''}schedule & model settings`);
+    if (brain?.model) console.log(`    - Model: ${brain.provider ? `${brain.provider} / ` : ''}${brain.model}`);
+    const written = models.filter(m => m.result === 'written' || m.result === 'kept-local').map(m => m.slug);
+    if (written.length) console.log(`    - Trained models: ${written.join(', ')}`);
+    const skipped = models.filter(m => m.result === 'invalid').map(m => m.slug);
+    if (skipped.length) console.log(`    - ${chalk.yellow(`Skipped models whose files didn't check out: ${skipped.join(', ')}`)}`);
+    console.log('');
+    console.log(brand.teal('  Not included:'));
+    console.log(`    - ${brand.gold('.env')} secrets (API keys etc.) stay on the machine they were set on.`);
+  } else {
+    console.log('');
+    console.log(brand.teal('  No saved setup on the network yet, so these are defaults:'));
+    console.log(`    - ${brand.gold('prompt.md')} (system prompt — generic template)`);
+    console.log(`    - ${brand.gold('tools.yaml')} (only the MyVillage tool is enabled)`);
+    console.log(`    - ${brand.gold('agent.config.yaml')} (anthropic + claude-sonnet by default)`);
+    console.log(`    Open the agent in Studio and save once on the original machine to publish it.`);
+  }
   console.log('');
   console.log(brand.teal('  Next:'));
   console.log(`    ${brand.gold(`myvillage agent edit ${agentName}`)}    Customize prompt / tools`);

package/src/commands/runner.js

@@ -3,6 +3,15 @@
  */
 import { createRequire } from 'module';
 import { runRunner, readRunnerState } from '../agent-runtime/runner.js';
+import { getAccessToken } from '../utils/auth.js';
+import {
+  describeRunnerService,
+  stageRunnerService,
+  runnerServiceStatus,
+  canSudo,
+  runWithSudo,
+  shellLine,
+} from '../utils/runner-service.js';
 
 function getCliVersion() {
   try {
@@ -37,4 +46,106 @@ export function runnerStatusCommand() {
   }
   console.log(`Machine:    ${state.name} (${state.machineId})`);
   console.log(`Registered: ${state.registeredAt}`);
+  try {
+    const spec = describeRunnerService();
+    const { installed, running } = runnerServiceStatus(spec);
+    const label = !installed ? 'not installed (run `myvillage runner install-service`)' : running ? 'installed, running' : 'installed, not running';
+    console.log(`Service:    ${label}`);
+    if (installed) console.log(`Log:        ${spec.logFile}`);
+  } catch { /* unsupported platform: nothing to report */ }
+}
+
+function printCommands(commands, spec) {
+  for (const [i, argv] of commands.entries()) {
+    const note = spec.platform === 'launchd' && argv[1] === 'bootout' && i === 0 ? '   # fine if it says not found' : '';
+    console.log(`  ${shellLine(argv)}${note}`);
+  }
+}
+
+export function runnerInstallServiceCommand(options = {}) {
+  let spec;
+  try {
+    spec = describeRunnerService({
+      name: options.name,
+      kind: options.kind,
+      capacity: options.capacity,
+      interval: options.interval,
+    });
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  if (process.getuid?.() === 0) {
+    console.error('Run this as the account the runner should run as, not as root. It will show or run the sudo steps itself.');
+    process.exit(1);
+  }
+
+  if (options.print) {
+    console.log(spec.content);
+    return;
+  }
+
+  // The service can't answer a login prompt, so the machine needs a credential
+  // before it boots unattended: a saved runner key, or a signed-in user.
+  const state = readRunnerState();
+  if (!state?.machineKey && !getAccessToken() && !process.env.MYVILLAGE_MACHINE_KEY) {
+    console.error('This machine has no runner credential yet. Run `myvillage login` (or `myvillage runner start` once) first.');
+    process.exit(1);
+  }
+
+  const copy = stageRunnerService(spec);
+  console.log(`Runner service for "${spec.user}" (${spec.platform}):`);
+  console.log(`  service file  ${spec.staged}   (copy: ${copy})`);
+  console.log(`  installs to   ${spec.target}`);
+  console.log(`  log           ${spec.logFile}`);
+  if (state?.pid) {
+    console.log('');
+    console.log(`Note: a runner is already running here (pid ${state.pid}). Stop it (Ctrl-C) once the service is up,`);
+    console.log('or the two will compete for the same agents.');
+  }
+  console.log('');
+
+  if (!options.yes && !canSudo()) {
+    console.log("This account isn't an admin, so an admin needs to run these once:");
+    printCommands(spec.install, spec);
+    console.log('');
+    console.log('Then check it with `myvillage runner status`.');
+    return;
+  }
+
+  console.log('Installing (sudo may ask for your password):');
+  printCommands(spec.install, spec);
+  const res = runWithSudo(spec.install, { ignoreFirstFailure: spec.platform === 'launchd' });
+  if (!res.ok) {
+    console.error(`\nFailed at: ${res.failed}`);
+    process.exit(1);
+  }
+  const { running } = runnerServiceStatus(spec);
+  console.log(running
+    ? '\nThe runner is installed and running. It will start at boot, before anyone logs in.'
+    : `\nInstalled, but it isn't running yet. Check ${spec.logFile}.`);
+}
+
+export function runnerUninstallServiceCommand(options = {}) {
+  let spec;
+  try {
+    spec = describeRunnerService();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  if (!options.yes && !canSudo()) {
+    console.log("This account isn't an admin, so an admin needs to run these to remove the runner service:");
+    printCommands(spec.uninstall, spec);
+    console.log('Agents already running keep running until stopped (`myvillage agent stop <name>`).');
+    return;
+  }
+  console.log('Removing the runner service (sudo may ask for your password):');
+  printCommands(spec.uninstall, spec);
+  const res = runWithSudo(spec.uninstall);
+  if (!res.ok) {
+    console.error(`\nFailed at: ${res.failed}`);
+    process.exit(1);
+  }
+  console.log('\nRemoved. Agents already running keep running until stopped (`myvillage agent stop <name>`).');
 }

package/src/index.js

@@ -82,7 +82,12 @@ import {
   agentRememberCommand,
   agentRecipesListCommand,
 } from './commands/agent-local.js';
-import { runnerStartCommand, runnerStatusCommand } from './commands/runner.js';
+import {
+  runnerStartCommand,
+  runnerStatusCommand,
+  runnerInstallServiceCommand,
+  runnerUninstallServiceCommand,
+} from './commands/runner.js';
 import {
   agentRegisterClientCommand,
   agentListClientsCommand,
@@ -1115,6 +1120,21 @@ export function run() {
     .command('status')
     .description("Show this machine's runner registration")
     .action(runnerStatusCommand);
+  runnerCmd
+    .command('install-service')
+    .description('Start the runner at boot as this user (launchd on macOS, systemd on Linux)')
+    .option('--name <name>', 'Machine name (default: the name it registered with)')
+    .option('--kind <kind>', 'Machine kind: laptop|mac|pi|spark|cloud|other')
+    .option('--capacity <n>', 'Soft cap on concurrently-run agents')
+    .option('--interval <sec>', 'Reconcile/heartbeat interval in seconds')
+    .option('--print', 'Only print the service file; install nothing')
+    .option('--yes', 'Run the sudo steps even if this account does not look like an admin')
+    .action(runnerInstallServiceCommand);
+  runnerCmd
+    .command('uninstall-service')
+    .description('Stop the runner service and remove it')
+    .option('--yes', 'Run the sudo steps even if this account does not look like an admin')
+    .action(runnerUninstallServiceCommand);
 
   program.parse();
 }

package/src/utils/agent-config-sync.js

@@ -0,0 +1,79 @@
+// Write an agent's published definition (GET /agents/:id/config) to its local
+// directory. Shared by the fleet runner, which keeps assigned agents in sync,
+// and `agent pull`, which rehydrates an agent on a new machine.
+//
+// `.env` is never written from the server: secrets stay per-machine until they
+// can be envelope-encrypted (see AgentConfig in the ed-platform schema).
+
+import fs from 'fs';
+import path from 'path';
+import { readAgentConfig, getAgentDir, writeAgentConfig } from './local-agent.js';
+import { writeSyncedModel } from './agent-models.js';
+
+// Records which published config version this machine last wrote, so the
+// runner only re-writes files when the definition actually changed.
+export function syncedVersionPath(agentDir) {
+  return path.join(agentDir, '.config-version');
+}
+
+export function readSyncedVersion(agentDir) {
+  try {
+    return Number(fs.readFileSync(syncedVersionPath(agentDir), 'utf8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Materialise a published config `c` into ~/.myvillage/agents/<name>/.
+ * Anything already set locally that the control plane does not own is kept.
+ * Returns { models: [{ slug, result }] } so callers can report what happened.
+ */
+export function writePublishedAgentConfig(name, c) {
+  const agentDir = getAgentDir(name);
+  fs.mkdirSync(agentDir, { recursive: true });
+
+  if (typeof c.promptMd === 'string' && c.promptMd) {
+    fs.writeFileSync(path.join(agentDir, 'prompt.md'), c.promptMd);
+  }
+  if (typeof c.toolsYaml === 'string' && c.toolsYaml) {
+    fs.writeFileSync(path.join(agentDir, 'tools.yaml'), c.toolsYaml);
+  }
+
+  // The trained models this agent was given travel with its config.
+  const models = [];
+  if (c.models && typeof c.models === 'object') {
+    for (const [slug, entry] of Object.entries(c.models)) {
+      models.push({ slug, result: writeSyncedModel(slug, entry) });
+    }
+  }
+
+  // Compose agent.config.yaml from server-known identity + published schedule
+  // and brain, preserving anything already set locally that the control plane
+  // does not own.
+  let existingCfg = {};
+  try { existingCfg = readAgentConfig(name) || {}; } catch { /* first sync */ }
+  const cfg = {
+    ...existingCfg,
+    name,
+    display_name: c.displayName || existingCfg.display_name || name,
+    description: c.description ?? existingCfg.description ?? '',
+    man: {
+      ...(existingCfg.man || {}),
+      agent_id: c.agentId,
+      ...(c.villageAgentId ? { village_agent_id: c.villageAgentId } : {}),
+      handle: c.handle || name,
+    },
+    ...(c.schedule ? { schedule: c.schedule } : {}),
+    ...(c.brain ? { brain: c.brain } : {}),
+  };
+  writeAgentConfig(name, cfg);
+
+  // Keep an empty .env so the daemon's loader and 0600 expectations hold, but
+  // never overwrite secrets a person put here.
+  const envPath = path.join(agentDir, '.env');
+  if (!fs.existsSync(envPath)) fs.writeFileSync(envPath, '', { mode: 0o600 });
+
+  if (c.version) fs.writeFileSync(syncedVersionPath(agentDir), String(c.version));
+  return { models };
+}

package/src/utils/api.js

@@ -302,6 +302,14 @@ export async function listMyAgents(options = {}) {
   return response.data;
 }
 
+// The agent's published definition (prompt, tools, schedule, model settings,
+// trained models). Studio republishes it on every save.
+export async function getAgentPublishedConfig(id) {
+  const client = getNetworkClient();
+  const response = await client.get(`/agents/${id}/config`);
+  return response.data?.data ?? response.data;
+}
+
 export async function getAgent(id) {
   const client = getNetworkClient();
   const response = await client.get(`/agents/${id}`);

package/src/utils/runner-service.js

@@ -0,0 +1,230 @@
+// Install the fleet runner as a boot-time service, so a machine keeps running
+// its assigned agents after a reboot or power cut with nobody logged in.
+//
+//   macOS → a LaunchDaemon in /Library/LaunchDaemons that runs as this user
+//   Linux → a systemd unit in /etc/systemd/system that runs as this user
+//
+// Both are system-level on purpose: a per-user LaunchAgent or user unit only
+// runs while someone is logged in. Installing one needs an admin, and the
+// account that runs agents usually isn't one, so the service file is staged
+// somewhere an admin can read it and the exact sudo commands are printed (or
+// run, when this account can sudo).
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const LOG_FILE = path.join(os.homedir(), '.myvillage', 'logs', 'runner.log');
+
+// The CLI's own entry point, resolved inside the installed package so it keeps
+// working across `npm update -g` (the package directory doesn't move).
+function cliEntryPath() {
+  return fs.realpathSync(fileURLToPath(new URL('../../bin/myvillage.js', import.meta.url)));
+}
+
+// Prefer a stable `node` on PATH over process.execPath when they are the same
+// binary: Homebrew's execPath points into a versioned Cellar dir that vanishes
+// on the next `brew upgrade`, while /opt/homebrew/bin/node follows it.
+function stableNodePath() {
+  const exec = fs.realpathSync(process.execPath);
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, 'node');
+    try {
+      if (fs.realpathSync(candidate) === exec) return candidate;
+    } catch { /* not here */ }
+  }
+  return process.execPath;
+}
+
+function servicePath(nodePath) {
+  const dirs = [path.dirname(nodePath)];
+  if (process.platform === 'darwin') dirs.push('/opt/homebrew/bin', '/opt/homebrew/sbin');
+  dirs.push('/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin');
+  return [...new Set(dirs)].join(':');
+}
+
+function runnerArgs(opts) {
+  const args = ['runner', 'start'];
+  if (opts.name) args.push('--name', String(opts.name));
+  if (opts.kind) args.push('--kind', String(opts.kind));
+  if (opts.capacity) args.push('--capacity', String(opts.capacity));
+  if (opts.interval) args.push('--interval', String(opts.interval));
+  return args;
+}
+
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// systemd splits ExecStart on whitespace; quote anything that needs it.
+const sdQuote = (s) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(s) ? s : `"${String(s).replace(/(["\\])/g, '\\$1')}"`);
+
+/**
+ * Describe the service for this machine and user. Pure apart from resolving
+ * paths, so it can be inspected (`--print`) before anything is installed.
+ */
+export function describeRunnerService(opts = {}) {
+  const user = os.userInfo().username;
+  const home = os.homedir();
+  const nodePath = stableNodePath();
+  const cliPath = cliEntryPath();
+  const program = [nodePath, cliPath, ...runnerArgs(opts)];
+  const env = { HOME: home, USER: user, LOGNAME: user, PATH: servicePath(nodePath), LANG: 'en_US.UTF-8' };
+
+  if (process.platform === 'darwin') {
+    const label = `ai.myvillage.runner.${user}`;
+    const target = `/Library/LaunchDaemons/${label}.plist`;
+    const content = `<?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>${xml(label)}</string>
+	<key>UserName</key>
+	<string>${xml(user)}</string>
+	<key>ProgramArguments</key>
+	<array>
+${program.map((a) => `\t\t<string>${xml(a)}</string>`).join('\n')}
+	</array>
+	<key>WorkingDirectory</key>
+	<string>${xml(home)}</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+${Object.entries(env).map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`).join('\n')}
+	</dict>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>ThrottleInterval</key>
+	<integer>10</integer>
+	<!-- Agent daemons outlive a runner restart; the runner re-adopts them. -->
+	<key>AbandonProcessGroup</key>
+	<true/>
+	<key>StandardOutPath</key>
+	<string>${xml(LOG_FILE)}</string>
+	<key>StandardErrorPath</key>
+	<string>${xml(LOG_FILE)}</string>
+</dict>
+</plist>
+`;
+    const staged = `/Users/Shared/${label}.plist`;
+    return {
+      platform: 'launchd',
+      user,
+      label,
+      target,
+      staged,
+      content,
+      logFile: LOG_FILE,
+      install: [
+        ['launchctl', 'bootout', `system/${label}`], // ignore failure: not loaded yet
+        ['install', '-m', '644', '-o', 'root', '-g', 'wheel', staged, target],
+        ['launchctl', 'bootstrap', 'system', target],
+      ],
+      uninstall: [
+        ['launchctl', 'bootout', `system/${label}`],
+        ['rm', '-f', target],
+      ],
+      statusCommand: ['launchctl', 'print', `system/${label}`],
+    };
+  }
+
+  if (process.platform === 'linux') {
+    const unit = `myvillage-runner-${user}.service`;
+    const target = `/etc/systemd/system/${unit}`;
+    const content = `[Unit]
+Description=MyVillage fleet runner (${user})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+WorkingDirectory=${home}
+${Object.entries(env).map(([k, v]) => `Environment=${sdQuote(`${k}=${v}`)}`).join('\n')}
+ExecStart=${program.map(sdQuote).join(' ')}
+Restart=always
+RestartSec=10
+# Agent daemons outlive a runner restart; the runner re-adopts them.
+KillMode=process
+StandardOutput=append:${LOG_FILE}
+StandardError=append:${LOG_FILE}
+
+[Install]
+WantedBy=multi-user.target
+`;
+    const staged = path.join('/tmp', unit);
+    return {
+      platform: 'systemd',
+      user,
+      label: unit,
+      target,
+      staged,
+      content,
+      logFile: LOG_FILE,
+      install: [
+        ['install', '-m', '644', '-o', 'root', '-g', 'root', staged, target],
+        ['systemctl', 'daemon-reload'],
+        ['systemctl', 'enable', unit],
+        ['systemctl', 'restart', unit],
+      ],
+      uninstall: [
+        ['systemctl', 'disable', '--now', unit],
+        ['rm', '-f', target],
+        ['systemctl', 'daemon-reload'],
+      ],
+      statusCommand: ['systemctl', 'is-active', unit],
+    };
+  }
+
+  throw new Error(`Installing the runner as a service isn't supported on ${process.platform} yet (macOS and Linux only).`);
+}
+
+/** Write the service file where an admin (including another account) can read it. */
+export function stageRunnerService(spec) {
+  fs.mkdirSync(path.dirname(spec.logFile), { recursive: true });
+  fs.writeFileSync(spec.staged, spec.content, { mode: 0o644 });
+  fs.chmodSync(spec.staged, 0o644);
+  // Keep a private copy next to the runner's state for reference.
+  const copy = path.join(os.homedir(), '.myvillage', 'service', path.basename(spec.target));
+  fs.mkdirSync(path.dirname(copy), { recursive: true });
+  fs.writeFileSync(copy, spec.content, { mode: 0o644 });
+  return copy;
+}
+
+export const shellLine = (argv) => `sudo ${argv.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(' ')}`;
+
+/**
+ * Can this account run admin commands? macOS: member of `admin`. Linux: member
+ * of `sudo` or `wheel`, or root. A guess, not a guarantee; sudo still decides.
+ */
+export function canSudo() {
+  if (process.getuid?.() === 0) return true;
+  const res = spawnSync('id', ['-Gn'], { encoding: 'utf8' });
+  const groups = (res.stdout || '').trim().split(/\s+/);
+  return groups.includes(process.platform === 'darwin' ? 'admin' : 'sudo') || groups.includes('wheel');
+}
+
+/** Run each command under sudo with the terminal attached (sudo may prompt). */
+export function runWithSudo(commands, { ignoreFirstFailure = false } = {}) {
+  for (const [i, argv] of commands.entries()) {
+    const res = spawnSync('sudo', argv, { stdio: 'inherit' });
+    if (res.status !== 0 && !(ignoreFirstFailure && i === 0)) {
+      return { ok: false, failed: shellLine(argv) };
+    }
+  }
+  return { ok: true };
+}
+
+/** Installed and running? Never needs sudo. */
+export function runnerServiceStatus(spec) {
+  const installed = fs.existsSync(spec.target);
+  const res = spawnSync(spec.statusCommand[0], spec.statusCommand.slice(1), { encoding: 'utf8' });
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  const running = spec.platform === 'launchd'
+    ? res.status === 0 && /\bstate = running\b/.test(out)
+    : res.status === 0 && out.trim() === 'active';
+  return { installed, running };
+}