robopark 2.8.36 → 3.0.0

package/dist/robopark/agent-ctl.js

@@ -0,0 +1,305 @@
+/**
+ * RoboPark — `robopark agent up/down/logs`.
+ *
+ * ROBOVOICE (the production voice stack: LiveKit + STT/TTS + agent) today
+ * requires an operator to manually `docker compose up -d` in that checkout,
+ * then manually `curl POST /api/servers` on the RoboPark scheduler to
+ * register the LiveKit instance it brought up. This file collapses both
+ * steps into one command so a hub/GPU machine only needs:
+ *
+ *   robopark setup --role hub
+ *   robopark agent-up --path C:\path\to\ROBOVOICE
+ *
+ * to be fully wired end to end.
+ *
+ * Reuses `roboparkServerAdd` (server-add.ts) for the exact POST /api/servers
+ * shape, and `resolveContext` (profile.ts) for hub/scheduler/token
+ * resolution with saved hub-profile fallback — nothing about the
+ * registration mechanics is reimplemented here.
+ */
+import { spawn, execFile } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { hostname, networkInterfaces } from 'node:os';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { roboparkServerAdd } from './server-add.js';
+import { resolveContext } from './profile.js';
+const LIVEKIT_PORT = 7880;
+const LIVEKIT_DEV_API_KEY = 'devkey';
+const LIVEKIT_DEV_API_SECRET = 'secret';
+/** This machine's first non-internal IPv4 LAN address, if any. */
+function getLanIps() {
+    const out = [];
+    for (const addrs of Object.values(networkInterfaces())) {
+        if (!addrs)
+            continue;
+        for (const a of addrs) {
+            if (a.family === 'IPv4' && !a.internal)
+                out.push(a.address);
+        }
+    }
+    return out;
+}
+/** Run `cmd version` quietly; resolve true if it exits 0. */
+function commandWorks(cmd, args) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { timeout: 8000 }, (err) => resolve(!err));
+    });
+}
+/**
+ * Detect whether to use Docker Compose v2 (`docker compose`, space-separated
+ * subcommand) or the legacy v1 standalone `docker-compose` binary. v2 is
+ * tried first since it's bundled with modern Docker Desktop/Engine; v1 is
+ * the fallback for older hosts that only have the standalone binary.
+ */
+async function resolveComposeCommand() {
+    if (await commandWorks('docker', ['compose', 'version'])) {
+        return { cmd: 'docker', baseArgs: ['compose'] };
+    }
+    if (await commandWorks('docker-compose', ['version'])) {
+        return { cmd: 'docker-compose', baseArgs: [] };
+    }
+    return null;
+}
+/** Spawn a compose subcommand, streaming stdout/stderr to the console. */
+function runCompose(compose, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(compose.cmd, [...compose.baseArgs, ...args], {
+            cwd,
+            stdio: 'inherit',
+        });
+        proc.on('error', reject);
+        proc.on('close', (code) => resolve(code ?? 1));
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Poll http://localhost:<port> until it responds (any HTTP status counts as "up" — LiveKit's bare HTTP port returns 404 for GET, which is fine). */
+async function waitForLivekitHealthy(port, timeoutMs, intervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`http://localhost:${port}/`, { signal: AbortSignal.timeout(2000) });
+            // LiveKit's plain HTTP listener answers (even 4xx) once the process is up.
+            if (res.status < 500)
+                return true;
+        }
+        catch {
+            // not up yet — fall through to retry
+        }
+        await sleep(intervalMs);
+    }
+    return false;
+}
+/** Validate that `path` looks like a ROBOVOICE checkout (has a docker-compose.yaml). */
+function validateComposePath(path) {
+    const candidates = ['docker-compose.yaml', 'docker-compose.yml'];
+    for (const name of candidates) {
+        const full = join(path, name);
+        if (existsSync(full))
+            return full;
+    }
+    throw new Error(`no docker-compose.yaml/.yml found in '${path}'. Pass --path pointing at a ROBOVOICE checkout ` +
+        `(the directory containing docker-compose.yaml), not this repo.`);
+}
+/** Persist the single-track greeting fix in a ROBOVOICE checkout. */
+function ensureRobovoiceSingleAudioTrack(path) {
+    const candidates = [
+        join(path, 'voice_agent.py'),
+        join(path, 'app', 'voice_agent.py'),
+        join(path, 'src', 'voice_agent.py'),
+    ];
+    const file = candidates.find((candidate) => existsSync(candidate));
+    if (!file) {
+        return { patched: false, warning: 'voice_agent.py was not found; skipping RoboPark greeting compatibility patch' };
+    }
+    const source = readFileSync(file, 'utf8');
+    let updated = source;
+    let patched = false;
+    const newline = source.includes('\r\n') ? '\r\n' : '\n';
+    const singleTrackMarker = 'Initial greeting completed through AgentSession audio track';
+    const startMarker = '            # Synthesize the greeting first';
+    const endMarker = '        except Exception as e:';
+    if (!updated.includes(singleTrackMarker)) {
+        const start = updated.indexOf(startMarker);
+        const end = start >= 0 ? updated.indexOf(endMarker, start) : -1;
+        if (start < 0 || end < 0) {
+            return {
+                patched: false,
+                file,
+                warning: 'voice_agent.py does not contain the known duplicate greeting-track block; no automatic patch applied',
+            };
+        }
+        const replacement = [
+            '            # Use the existing conversation track. A dedicated greeting',
+            '            # track makes Linux robots compete for the same ALSA device.',
+            '            import inspect as _inspect',
+            '            speech = session.say(greeting, allow_interruptions=False)',
+            '            if _inspect.isawaitable(speech):',
+            '                await speech',
+            "            elif hasattr(speech, 'wait_for_playout'):",
+            '                await speech.wait_for_playout()',
+            "            logger.info('Initial greeting completed through AgentSession audio track')",
+            '',
+        ].join(newline);
+        updated = updated.slice(0, start) + replacement + updated.slice(end);
+        patched = true;
+    }
+    // The job is dispatched after the robot participant joins. Waiting for its
+    // camera adds camera startup to voice latency even though audio is ready.
+    const cameraGate = /            await asyncio\.wait_for\(robot_camera_ready\.wait\(\), timeout\s*=\s*[0-9.]+\)/;
+    if (cameraGate.test(updated)) {
+        updated = updated.replace(cameraGate, [
+            '            # The robot is already in the room when this job is dispatched.',
+            '            # Yield once for subscription signalling; do not gate voice on camera.',
+            '            await asyncio.sleep(0)',
+        ].join(newline));
+        patched = true;
+    }
+    if (patched)
+        writeFileSync(file, updated, 'utf8');
+    return { patched, file };
+}
+export async function roboparkAgentUp(opts) {
+    console.log(chalk.bold('\n  robopark agent up'));
+    console.log(chalk.dim('  ' + '─'.repeat(52)));
+    if (!existsSync(opts.path)) {
+        console.log(chalk.red(`  ✗ path does not exist: ${opts.path}`));
+        process.exit(1);
+    }
+    try {
+        validateComposePath(opts.path);
+    }
+    catch (e) {
+        console.log(chalk.red(`  ✗ ${e.message}`));
+        process.exit(1);
+    }
+    const compose = await resolveComposeCommand();
+    if (!compose) {
+        console.log(chalk.red('  ✗ neither `docker compose` (v2) nor `docker-compose` (v1) is available on PATH.'));
+        process.exit(1);
+    }
+    console.log(chalk.dim(`  using: ${compose.cmd} ${compose.baseArgs.join(' ')}`.trimEnd()));
+    console.log(`  path:  ${chalk.cyan(opts.path)}`);
+    console.log();
+    const greetingPatch = ensureRobovoiceSingleAudioTrack(opts.path);
+    if (greetingPatch.patched) {
+        console.log(chalk.green(`  ✓ persisted single-track RoboPark greeting in ${greetingPatch.file}`));
+    }
+    else if (greetingPatch.warning) {
+        console.log(chalk.yellow(`  ⚠ ${greetingPatch.warning}`));
+    }
+    console.log(chalk.bold('  1. starting ROBOVOICE docker stack (docker compose up -d)…'));
+    // Rebuild only when compatibility source changed, making the fix survive
+    // container recreation without slowing normal restarts.
+    const upArgs = greetingPatch.patched ? ['up', '-d', '--build'] : ['up', '-d'];
+    const upCode = await runCompose(compose, upArgs, opts.path);
+    if (upCode !== 0) {
+        console.log(chalk.red(`\n  ✗ docker compose up -d exited with code ${upCode}`));
+        process.exit(upCode);
+    }
+    console.log(chalk.green('  ✓ docker compose up -d completed'));
+    console.log();
+    console.log(chalk.bold(`  2. waiting for LiveKit to become healthy on :${LIVEKIT_PORT} (up to 60s)…`));
+    const healthy = await waitForLivekitHealthy(LIVEKIT_PORT, 60_000, 3_000);
+    if (!healthy) {
+        console.log(chalk.red(`  ✗ LiveKit did not respond on http://localhost:${LIVEKIT_PORT} within 60s.`));
+        console.log(chalk.dim(`    check container health: ${compose.cmd} ${compose.baseArgs.join(' ')} ps`.trim()));
+        process.exit(1);
+    }
+    console.log(chalk.green(`  ✓ LiveKit is up on :${LIVEKIT_PORT}`));
+    if (opts.register === false) {
+        console.log();
+        console.log(chalk.dim('  --no-register passed; skipping scheduler registration.'));
+        console.log(chalk.green('\n  ✓ robopark agent up complete (docker only)\n'));
+        return;
+    }
+    console.log();
+    console.log(chalk.bold('  3. registering LiveKit server with the RoboPark scheduler…'));
+    const ctx = await resolveContext({ hubUrl: opts.hubUrl, token: opts.token, schedulerUrl: opts.schedulerUrl });
+    if (!ctx.schedulerUrl) {
+        console.log(chalk.red('  ✗ no scheduler URL resolved. Pass --scheduler-url/--hub-url, or run `robopark setup --role hub` first.'));
+        process.exit(1);
+    }
+    // Advertise this machine's own reachable address. This is a best-effort
+    // guess (first non-internal LAN IPv4); if the scheduler runs on a
+    // *different* machine than the one running `agent up` and that machine
+    // can't reach this LAN IP (e.g. NAT, VPN split), correct the registration
+    // manually afterwards with `robopark server-add --id <id> --url ws://<correct-host>:7880`.
+    const lanIps = getLanIps();
+    const advertiseHost = lanIps[0] ?? hostname();
+    if (lanIps.length === 0) {
+        console.log(chalk.yellow(`  ⚠ no LAN IPv4 detected; advertising hostname '${advertiseHost}'. Correct with 'robopark server-add' if the scheduler can't resolve it.`));
+    }
+    const id = opts.serverId ?? `robovoice-${hostname()}`;
+    const name = opts.serverName ?? `ROBOVOICE (${hostname()})`;
+    const url = `ws://${advertiseHost}:${LIVEKIT_PORT}`;
+    await roboparkServerAdd({
+        hubUrl: ctx.hubUrl,
+        schedulerUrl: ctx.schedulerUrl,
+        token: ctx.token,
+        id,
+        name,
+        url,
+        apiKey: LIVEKIT_DEV_API_KEY,
+        apiSecret: LIVEKIT_DEV_API_SECRET,
+    });
+    console.log(chalk.green('\n  ✓ robopark agent up complete — ROBOVOICE is running and registered with the scheduler\n'));
+}
+export async function roboparkAgentDown(opts) {
+    console.log(chalk.bold('\n  robopark agent down'));
+    console.log(chalk.dim('  ' + '─'.repeat(52)));
+    if (!existsSync(opts.path)) {
+        console.log(chalk.red(`  ✗ path does not exist: ${opts.path}`));
+        process.exit(1);
+    }
+    try {
+        validateComposePath(opts.path);
+    }
+    catch (e) {
+        console.log(chalk.red(`  ✗ ${e.message}`));
+        process.exit(1);
+    }
+    const compose = await resolveComposeCommand();
+    if (!compose) {
+        console.log(chalk.red('  ✗ neither `docker compose` (v2) nor `docker-compose` (v1) is available on PATH.'));
+        process.exit(1);
+    }
+    console.log(`  path: ${chalk.cyan(opts.path)}`);
+    console.log();
+    const code = await runCompose(compose, ['down'], opts.path);
+    if (code !== 0) {
+        console.log(chalk.red(`\n  ✗ docker compose down exited with code ${code}`));
+        process.exit(code);
+    }
+    console.log(chalk.green('\n  ✓ ROBOVOICE stack stopped\n'));
+}
+export async function roboparkAgentLogs(opts) {
+    if (!existsSync(opts.path)) {
+        console.log(chalk.red(`  ✗ path does not exist: ${opts.path}`));
+        process.exit(1);
+    }
+    try {
+        validateComposePath(opts.path);
+    }
+    catch (e) {
+        console.log(chalk.red(`  ✗ ${e.message}`));
+        process.exit(1);
+    }
+    const compose = await resolveComposeCommand();
+    if (!compose) {
+        console.log(chalk.red('  ✗ neither `docker compose` (v2) nor `docker-compose` (v1) is available on PATH.'));
+        process.exit(1);
+    }
+    const args = ['logs'];
+    if (opts.follow)
+        args.push('-f');
+    if (opts.service)
+        args.push(opts.service);
+    // Live tail: no buffering, no capture — inherit stdio directly.
+    const code = await runCompose(compose, args, opts.path);
+    if (code !== 0 && !opts.follow) {
+        process.exit(code);
+    }
+}

package/dist/robopark/auto-start.js

@@ -0,0 +1,289 @@
+/**
+ * RoboPark — auto-start registration for production machines.
+ *
+ * Registers the RoboPark service to start on boot:
+ *   - Windows → Task Scheduler
+ *   - Linux   → systemd
+ *   - macOS   → launchd
+ *
+ * This is used by `robopark setup --auto-start`.
+ */
+import { existsSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+function shellQuote(s) {
+    if (!/[^a-zA-Z0-9_./:=,-]/.test(s))
+        return s;
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+export async function registerAutoStart(service) {
+    const platform = process.platform;
+    if (platform === 'win32')
+        return registerWindows(service);
+    if (platform === 'linux')
+        return registerSystemd(service);
+    if (platform === 'darwin')
+        return registerLaunchd(service);
+    return { ok: false, message: `auto-start not supported on ${platform}` };
+}
+async function registerWindows(service) {
+    const taskName = `RoboPark-${service.role}-${service.name}`;
+    const logDir = join(homedir(), 'AppData', 'Roaming', 'robopark', 'logs');
+    mkdirSync(logDir, { recursive: true });
+    const outLog = join(logDir, `${taskName}.log`);
+    const errLog = join(logDir, `${taskName}.err.log`);
+    const invocation = [service.command, ...service.args].map(shellQuote).join(' ');
+    const script = `& ${invocation} 1>> ${shellQuote(outLog)} 2>> ${shellQuote(errLog)}`;
+    const cmd = ['powershell.exe', '-WindowStyle', 'Hidden', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script];
+    const xmlPath = join(homedir(), 'AppData', 'Roaming', 'robopark', `${taskName}.xml`);
+    mkdirSync(dirname(xmlPath), { recursive: true });
+    const xml = `<?xml version="1.0" encoding="UTF-16"?>\n<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">\n  <RegistrationInfo>\n    <Description>RoboPark ${service.role} for ${service.name}</Description>\n  </RegistrationInfo>\n  <Triggers>\n    <BootTrigger>\n      <Enabled>true</Enabled>\n    </BootTrigger>\n    <LogonTrigger>\n      <Enabled>true</Enabled>\n    </LogonTrigger>\n  </Triggers>\n  <Principals>\n    <Principal id="Author">\n      <LogonType>S4U</LogonType>\n      <RunLevel>HighestAvailable</RunLevel>\n    </Principal>\n  </Principals>\n  <Settings>\n    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>\n    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>\n    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>\n    <StartWhenAvailable>true</StartWhenAvailable>\n    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>\n    <IdleSettings>\n      <StopOnIdleEnd>false</StopOnIdleEnd>\n      <RestartOnIdle>false</RestartOnIdle>\n    </IdleSettings>\n    <AllowStartOnDemand>true</AllowStartOnDemand>\n    <Enabled>true</Enabled>\n    <Hidden>false</Hidden>\n    <RunOnlyIfIdle>false</RunOnlyIfIdle>\n    <DisallowStartOnRemoteAppSession>false</DisallowStartOnRemoteAppSession>\n    <UseUnifiedSchedulingEngine>true</UseUnifiedSchedulingEngine>\n    <WakeToRun>false</WakeToRun>\n    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>\n  </Settings>\n  <Actions Context="Author">\n    <Exec>\n      <Command>${cmd[0]}</Command>\n      <Arguments>${cmd.slice(1).map(a => a.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')).join(' ')}</Arguments>\n      <WorkingDirectory>${service.workingDir ?? homedir()}</WorkingDirectory>\n    </Exec>\n  </Actions>\n</Task>`;
+    const hardenedXml = xml.replace('  </Settings>', '    <RestartOnFailure>\n      <Interval>PT5S</Interval>\n      <Count>999</Count>\n    </RestartOnFailure>\n  </Settings>');
+    // schtasks /XML requires UTF-16 LE *with* BOM when the XML declares UTF-16.
+    const bom = Buffer.from([0xff, 0xfe]);
+    const body = Buffer.from(hardenedXml, 'utf16le');
+    writeFileSync(xmlPath, Buffer.concat([bom, body]));
+    return new Promise((resolve) => {
+        const schtasks = spawn('schtasks', ['/Create', '/TN', taskName, '/XML', xmlPath, '/F'], { stdio: 'pipe' });
+        let out = '';
+        let err = '';
+        schtasks.stdout.on('data', d => (out += d.toString()));
+        schtasks.stderr.on('data', d => (err += d.toString()));
+        schtasks.on('close', code => {
+            if (code === 0) {
+                const started = spawnSync('schtasks', ['/Run', '/TN', taskName], { encoding: 'utf8' });
+                if (started.status === 0) {
+                    resolve({ ok: true, message: `registered and started Windows Task Scheduler task "${taskName}"` });
+                }
+                else {
+                    resolve({ ok: false, message: `registered "${taskName}", but could not start it: ${started.stderr || started.stdout}` });
+                }
+            }
+            else {
+                resolve({ ok: false, message: `schtasks failed (${code}): ${err || out}` });
+            }
+        });
+        schtasks.on('error', e => resolve({ ok: false, message: `could not run schtasks: ${e.message}` }));
+    });
+}
+async function registerSystemd(service) {
+    const unitName = `robopark-${service.role}-${service.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.service`;
+    const unitPath = `/etc/systemd/system/${unitName}`;
+    const envLines = Object.entries(service.env ?? {})
+        .map(([k, v]) => `Environment="${k}=${v.replace(/"/g, '\\"')}"`)
+        .join('\n');
+    const mediaService = service.role === 'robot-runtime' || service.role === 'robot-preview-agent' || service.role === 'robot-vision-agent' || service.role === 'robot-motor' || service.role === 'robot-conversation' || service.role === 'robot-screen';
+    const mediaGroups = mediaService
+        ? ['audio', 'video', 'render', 'input', 'plugdev', 'gpio'].filter(group => spawnSync('getent', ['group', group], { stdio: 'ignore' }).status === 0)
+        : [];
+    const mediaPolicy = mediaService ? [
+        mediaGroups.length ? `SupplementaryGroups=${mediaGroups.join(' ')}` : '',
+        'UMask=0007',
+        'LimitNOFILE=65536',
+        'TasksMax=512',
+        'OOMScoreAdjust=-500',
+    ].filter(Boolean).join('\n') : '';
+    const restartSeconds = service.role === 'robot-conversation' ? 1 : 3;
+    const startLimit = service.role === 'robot-conversation'
+        ? 'StartLimitIntervalSec=0'
+        : 'StartLimitIntervalSec=120\nStartLimitBurst=20';
+    // Conversation ownership is coordinated by canonical service retirement
+    // below and by the local media lease. Never kill desktop audio daemons,
+    // cameras, or unrelated ALSA owners as a side effect of starting voice.
+    const exclusiveMediaPreflight = service.exclusiveMedia && service.role !== 'robot-conversation'
+        ? "ExecStartPre=/bin/sh -c 'command -v fuser >/dev/null 2>&1 || exit 1; fuser -s /dev/snd/* /dev/video* >/dev/null 2>&1 && exit 1 || exit 0'"
+        : '';
+    const motorPreflight = service.role === 'robot-motor'
+        ? "ExecStartPre=-/bin/sh -c 'command -v fuser >/dev/null 2>&1 && fuser -k -TERM 8001/tcp >/dev/null 2>&1 || true; sleep 1'"
+        : '';
+    let mediaRulesInstalled = false;
+    if (mediaService) {
+        const rulesPath = '/etc/udev/rules.d/70-robopark-media.rules';
+        const rules = [
+            '# Managed by RoboPark. Shared hardware profile for production robots.',
+            'SUBSYSTEM=="video4linux", GROUP="video", MODE="0660"',
+            'SUBSYSTEM=="video4linux", ENV{ID_BUS}=="usb", ATTR{index}=="0", SYMLINK+="robopark-camera"',
+            'SUBSYSTEM=="sound", GROUP="audio", MODE="0660"',
+            '',
+        ].join('\n');
+        try {
+            writeFileSync(rulesPath, rules, 'utf8');
+            spawnSync('udevadm', ['control', '--reload-rules'], { stdio: 'ignore' });
+            spawnSync('udevadm', ['trigger', '--subsystem-match=video4linux'], { stdio: 'ignore' });
+            spawnSync('udevadm', ['trigger', '--subsystem-match=sound'], { stdio: 'ignore' });
+            mediaRulesInstalled = true;
+        }
+        catch {
+            // The explicit systemd groups below still cover standard distro rules.
+        }
+    }
+    const unit = `[Unit]
+Description=RoboPark ${service.role} for ${service.name}
+After=network-online.target sound.target
+Wants=network-online.target sound.target
+${startLimit}
+
+[Service]
+Type=simple
+${exclusiveMediaPreflight}
+${motorPreflight}
+ExecStart=${service.command} ${service.args.map(shellQuote).join(' ')}
+WorkingDirectory=${service.workingDir ?? homedir()}
+Restart=always
+RestartSec=${restartSeconds}
+KillMode=control-group
+TimeoutStopSec=20
+SendSIGKILL=yes
+FinalKillSignal=SIGKILL
+${mediaPolicy}
+${envLines}
+
+[Install]
+WantedBy=multi-user.target
+`;
+    try {
+        writeFileSync(unitPath, unit, 'utf8');
+        const retiredUnits = [];
+        if (service.role === 'robot-conversation') {
+            // A Pi has one physical microphone/speaker pair. Historical robot names
+            // must not leave Restart=always workers racing the selected character.
+            const discovered = new Set();
+            for (const args of [
+                ['list-unit-files', 'robopark-robot-conversation-*.service', '--no-legend', '--no-pager'],
+                ['list-units', '--all', 'robopark-robot-conversation-*.service', '--no-legend', '--no-pager'],
+            ]) {
+                const listed = spawnSync('systemctl', args, { encoding: 'utf8' });
+                for (const line of String(listed.stdout ?? '').split(/\r?\n/)) {
+                    const candidate = line.trim().split(/\s+/, 1)[0];
+                    if (/^robopark-robot-conversation-[a-z0-9-]+\.service$/.test(candidate)) {
+                        discovered.add(candidate);
+                    }
+                }
+            }
+            for (const candidate of discovered) {
+                if (candidate === unitName)
+                    continue;
+                spawnSync('systemctl', ['disable', '--now', candidate], { stdio: 'ignore' });
+                spawnSync('systemctl', ['kill', '--kill-who=all', '--signal=SIGKILL', candidate], { stdio: 'ignore' });
+                const stalePath = `/etc/systemd/system/${candidate}`;
+                try {
+                    if (existsSync(stalePath))
+                        rmSync(stalePath);
+                }
+                catch { /* daemon reload below reconciles state */ }
+                retiredUnits.push(candidate);
+            }
+        }
+        const reload = spawnSync('systemctl', ['daemon-reload'], { encoding: 'utf8' });
+        if (reload.status !== 0) {
+            return { ok: false, message: `wrote ${unitPath}, but systemctl daemon-reload failed: ${reload.stderr || reload.stdout}` };
+        }
+        const enabled = spawnSync('systemctl', ['enable', unitName], { encoding: 'utf8' });
+        if (enabled.status !== 0) {
+            return { ok: false, message: `wrote ${unitPath}, but systemctl enable failed: ${enabled.stderr || enabled.stdout}` };
+        }
+        // `enable --now` leaves an already-running unit untouched. Always restart
+        // so the newly written config and exclusive-device preflight take effect.
+        const restarted = spawnSync('systemctl', ['restart', unitName], { encoding: 'utf8' });
+        if (restarted.status !== 0) {
+            return { ok: false, message: `enabled ${unitName}, but systemctl restart failed: ${restarted.stderr || restarted.stdout}` };
+        }
+        return {
+            ok: true,
+            message: `enabled and started systemd unit ${unitName}${mediaRulesInstalled ? ' with persistent media permissions' : ''}`
+                + (retiredUnits.length ? `; retired ${retiredUnits.join(', ')}` : ''),
+        };
+    }
+    catch (e) {
+        return { ok: false, message: `could not write ${unitPath}: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}
+async function registerLaunchd(service) {
+    const label = `ai.robopark.${service.role}.${service.name}`;
+    const plistPath = join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+    mkdirSync(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true });
+    const env = service.env ?? {};
+    const envBlock = Object.keys(env).length
+        ? `<key>EnvironmentVariables</key>
+  <dict>
+    ${Object.entries(env).map(([k, v]) => `<key>${k}</key>\n    <string>${v}</string>`).join('\n    ')}
+  </dict>`
+        : '';
+    const plist = `<?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>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${service.command}</string>
+    ${service.args.map(a => `<string>${a.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')}</string>`).join('\n    ')}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${service.workingDir ?? homedir()}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${join(homedir(), 'Library', 'Logs', `${label}.log`)}</string>
+  <key>StandardErrorPath</key>
+  <string>${join(homedir(), 'Library', 'Logs', `${label}.err.log`)}</string>
+  ${envBlock}
+</dict>
+</plist>`;
+    try {
+        writeFileSync(plistPath, plist, 'utf8');
+        spawnSync('launchctl', ['unload', plistPath], { stdio: 'ignore' });
+        const loaded = spawnSync('launchctl', ['load', '-w', plistPath], { encoding: 'utf8' });
+        if (loaded.status !== 0) {
+            return { ok: false, message: `wrote ${plistPath}, but launchctl failed: ${loaded.stderr || loaded.stdout}` };
+        }
+        return { ok: true, message: `registered and started launchd service ${label}` };
+    }
+    catch (e) {
+        return { ok: false, message: `could not write ${plistPath}: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}
+export function unregisterAutoStart(role, name) {
+    const platform = process.platform;
+    const taskName = `RoboPark-${role}-${name}`;
+    if (platform === 'win32') {
+        try {
+            spawn('schtasks', ['/Delete', '/TN', taskName, '/F'], { stdio: 'ignore' }).unref();
+            return { ok: true, message: `deleted Windows task "${taskName}"` };
+        }
+        catch (e) {
+            return { ok: false, message: `failed: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    if (platform === 'linux') {
+        const unitName = `robopark-${role}-${name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.service`;
+        const unitPath = `/etc/systemd/system/${unitName}`;
+        const stopped = spawnSync('systemctl', ['disable', '--now', unitName], { encoding: 'utf8' });
+        try {
+            if (existsSync(unitPath))
+                rmSync(unitPath);
+        }
+        catch { /* systemd output is more useful below */ }
+        spawnSync('systemctl', ['daemon-reload'], { stdio: 'ignore' });
+        return {
+            ok: stopped.status === 0 || !existsSync(unitPath),
+            message: `removed systemd unit ${unitName}`,
+        };
+    }
+    if (platform === 'darwin') {
+        const label = `ai.robopark.${role}.${name}`;
+        const plistPath = join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+        spawnSync('launchctl', ['unload', plistPath], { stdio: 'ignore' });
+        try {
+            if (existsSync(plistPath))
+                rmSync(plistPath);
+        }
+        catch { /* ignore */ }
+        return { ok: true, message: `removed launchd plist ${plistPath}` };
+    }
+    return { ok: false, message: `unregister not supported on ${platform}` };
+}