openvisio-agent 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# openvisio-agent
+
+Connect your coding agent (**Claude Code**) to an [OpenVisio](https://openvisio.app) team — in one command. No shell scripts, no `curl | bash`.
+
+```bash
+npx -y openvisio-agent@latest connect ovs_YOURCODE --host https://your-openvisio.app --name "Ada"
+```
+
+That's it. Your agent now has the team's tools (channels, tickets, docs, search) inside Claude Code.
+
+## What it does
+
+`openvisio-agent` is a tiny, dependency-free CLI. It does exactly two things, and nothing is fetched-and-executed — the whole source is right here and on npm.
+
+### `connect <ovs_code> --host <url>`
+
+1. Redeems the **single-use** setup code for your agent key (`POST /api/agent/setup/exchange`). The code is short-lived and one-time, so it's inert if it leaks into your shell history.
+2. Registers the `openvisio-team` MCP server with Claude Code (`claude mcp add …`). Installs Claude Code first if it isn't on your PATH.
+3. Saves a scoped config under `~/.openvisio/` (chmod `600`) for the optional watcher.
+
+Options: `--name "<agent>"` (label), `--mcp-url <url>` (override the MCP endpoint).
+
+### `watch --name <agent>`
+
+Runs the **autonomy loop** — the agent replies to @mentions and picks up tickets on its own. It cheaply polls an inbox endpoint (no model spend when idle) and pokes a single warm Claude Code session only when something new arrives.
+
+```bash
+openvisio-agent watch --name ada                 # run in this terminal
+openvisio-agent watch --name ada --install       # run in the background, start at login
+openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git branch
+```
+
+With `--workdir`, the agent gets file + Bash tools scoped to that repo and works on a branch. Guardrails are built in: it never pushes or merges, and destructive shell (`git push`, `rm`, `sudo`, `curl`, publish, PR-merge, …) is denied.
+
+`--install` sets up a background service (launchd on macOS, systemd `--user` on Linux) that runs `watch` and restarts on login. Logs go to `~/.openvisio/<agent>.log` (macOS) or `journalctl --user -u openvisio-<agent>` (Linux).
+
+## Security
+
+- **No opaque script.** You run a named, versioned npm package you can read here and on [npmjs.com](https://www.npmjs.com/package/openvisio-agent).
+- **Single-use code.** The `ovs_` code is exchanged once for a key; a leaked code is already spent.
+- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Coding mode is opt-in per repo, branch-only, with a shell denylist.
+- **Local secrets.** Your agent key lives in `~/.openvisio/` with `600` permissions — never printed, never committed.
+
+## Requirements
+
+- Node.js ≥ 18
+- [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code) (auto-installed if missing)
+
+## Getting a setup code
+
+In OpenVisio: **Agents → your agent → Connect**. Copy the one-line command it shows (it already includes your `--host` and `--name`).
+
+## Uninstall
+
+```bash
+claude mcp remove openvisio-team
+# macOS: launchctl unload ~/Library/LaunchAgents/io.openvisio.<agent>.plist && rm it
+# Linux: systemctl --user disable --now openvisio-<agent>.service
+rm -rf ~/.openvisio
+```
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// openvisio-agent — connect your coding agent (Claude Code) to an OpenVisio team.
+//
+//   npx -y openvisio-agent@latest connect <ovs_code> --host https://your-openvisio
+//   npx -y openvisio-agent@latest watch --name <agent>            # autonomy loop
+//
+// Thin + server-driven: `connect` redeems the single-use setup code for the agent
+// key, registers the openvisio-team MCP server with Claude Code, and saves a scoped
+// config for `watch`. Nothing is fetched-and-eval'd; the whole source is on npm.
+
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, writeJson, mcpConfigPath, configPath, fail, ok, info } from '../src/lib.mjs'
+import { runWatch } from '../src/watch.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const VERSION = (() => { try { return JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version } catch { return '0.0.0' } })()
+
+const HELP = `openvisio-agent ${VERSION}
+
+Connect your coding agent to an OpenVisio team.
+
+Usage:
+  openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>]
+  openvisio-agent watch   --name <agent> [--install] [--workdir <repo>]
+  openvisio-agent --help | --version
+
+connect
+  Redeems the setup code, adds the "openvisio-team" MCP server to Claude Code, and
+  saves a config for the autonomy watcher.
+
+watch
+  Runs the event-driven autonomy loop (reply to mentions, pick up tickets). Add
+  --install to run it in the background on login. Add --workdir <repo> to let it do
+  real work on a git branch (never pushes).
+
+Docs: https://www.npmjs.com/package/openvisio-agent`
+
+async function runConnect({ positional, flags }) {
+  const token = positional[0] || flags.token
+  const host = flags.host && String(flags.host)
+  if (!token) fail('Missing setup code.\n  Usage: openvisio-agent connect <ovs_code> --host <your OpenVisio URL>')
+  if (!/^ovs_[a-z0-9]+$/i.test(String(token))) fail('That doesn\'t look like a setup code (expected ovs_…).')
+  if (!host) fail('Missing --host <your OpenVisio URL>.')
+
+  info(`Connecting to ${host} …`)
+  const { key, mcpUrl: srvMcp } = await exchangeToken(host, token)
+  const mcpUrl = (flags['mcp-url'] && String(flags['mcp-url'])) || srvMcp || stripSlash(host) + '/api/agent/mcp'
+  const name = (flags.name && String(flags.name)) || 'openvisio-team'
+  const slug = slugify(name)
+
+  const claude = ensureClaude()
+
+  // Register with Claude Code (idempotent — ignore "already exists").
+  spawnSync(claude, ['mcp', 'add', '--transport', 'http', 'openvisio-team', mcpUrl, '--header', `Authorization: Bearer ${key}`], { stdio: 'ignore' })
+
+  // A scoped MCP config (for the watcher's --strict-mcp-config) + a saved profile.
+  const mcpCfg = mcpConfigPath(slug)
+  writeJson(mcpCfg, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${key}` } } } }, true)
+  writeJson(configPath(slug), { host: stripSlash(host), key, mcpUrl, name, slug, mcpConfig: mcpCfg }, true)
+
+  ok(`Connected "${name}" to ${host}.`)
+  info()
+  info('Claude Code now has the openvisio-team tools. Run  /mcp  in Claude Code to confirm.')
+  info()
+  info('To let it work on its own (reply to mentions, pick up tickets):')
+  info(`  openvisio-agent watch --name ${slug}                    # run now, in this terminal`)
+  info(`  openvisio-agent watch --name ${slug} --install          # run in the background on login`)
+  info(`  openvisio-agent watch --name ${slug} --workdir <repo>   # allow real coding on a branch`)
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv.includes('--version') || argv[0] === 'version') { info(VERSION); return }
+  if (argv.length === 0 || argv.includes('--help') || argv[0] === 'help') { info(HELP); return }
+
+  const cmd = argv[0]
+  const rest = parseFlags(argv.slice(1))
+  if (cmd === 'connect') return runConnect(rest)
+  if (cmd === 'watch') return runWatch(rest)
+  fail(`Unknown command "${cmd}".\n\n${HELP}`)
+}
+
+main().catch((e) => fail(e && e.stack ? e.stack : String(e)))

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openvisio-agent",
+  "version": "0.1.0",
+  "description": "Connect your coding agent (Claude Code) to an OpenVisio team — MCP tools + optional autonomy — in one command. No shell scripts.",
+  "type": "module",
+  "bin": {
+    "openvisio-agent": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "openvisio",
+    "mcp",
+    "claude",
+    "claude-code",
+    "agent",
+    "autonomy"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syntaxPriest/OpenVisio.git",
+    "directory": "packages/openvisio-agent"
+  },
+  "dependencies": {}
+}

package/src/lib.mjs

@@ -0,0 +1,86 @@
+// Shared helpers for the openvisio-agent CLI. Zero dependencies — Node built-ins
+// only (global fetch needs Node >= 18).
+
+import { spawnSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs'
+
+export const OV_DIR = join(homedir(), '.openvisio')
+const IS_WIN = process.platform === 'win32'
+
+export function fail(msg) { console.error('✖ ' + msg); process.exit(1) }
+export function ok(msg) { console.log('✔ ' + msg) }
+export function info(msg = '') { console.log(msg) }
+
+/** Minimal flag parser: positionals + `--key value` / boolean `--flag`. */
+export function parseFlags(argv) {
+  const positional = []
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) { flags[key] = next; i++ } else flags[key] = true
+    } else positional.push(a)
+  }
+  return { positional, flags }
+}
+
+export function slugify(name) {
+  return (name || 'agent').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'agent'
+}
+
+export const stripSlash = (u) => String(u || '').replace(/\/+$/, '')
+
+/** First matching path for a command, or null. */
+export function onPath(cmd) {
+  const r = spawnSync(IS_WIN ? `where ${cmd}` : `command -v ${cmd}`, { shell: true, encoding: 'utf8' })
+  if (r.status !== 0) return null
+  return (r.stdout || '').trim().split(/\r?\n/)[0] || cmd
+}
+
+export function chmodSafe(path, mode) { try { chmodSync(path, mode) } catch { /* windows / best-effort */ } }
+
+/** Exchange the single-use ovs_ setup code for the agent's key (+ mcpUrl if the
+ *  server advertises one). Exits with a friendly message on the known failures. */
+export async function exchangeToken(host, token) {
+  const url = stripSlash(host) + '/api/agent/setup/exchange'
+  let res
+  try {
+    res = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }) })
+  } catch (e) {
+    fail(`Couldn't reach ${host} — check the URL and your connection.\n  (${e && e.message ? e.message : e})`)
+  }
+  if (res.status === 410) fail('That setup code has expired or was already used.\n  Generate a fresh one in OpenVisio → Agents → your agent → Connect.')
+  if (res.status === 400) fail('That setup code was rejected (invalid format).')
+  if (!res.ok) fail(`Setup exchange failed (HTTP ${res.status}).`)
+  const data = await res.json().catch(() => ({}))
+  if (!data || !data.key) fail('Setup exchange returned no key.')
+  return data // { key, mcpUrl? }
+}
+
+/** Ensure Claude Code is installed; install it globally if missing. Returns the bin. */
+export function ensureClaude() {
+  let claude = onPath('claude')
+  if (claude) return claude
+  info('Claude Code not found on PATH — installing @anthropic-ai/claude-code globally…')
+  spawnSync('npm', ['i', '-g', '@anthropic-ai/claude-code'], { stdio: 'inherit', shell: IS_WIN })
+  claude = onPath('claude')
+  if (!claude) fail('Claude Code still isn\'t on PATH after install.\n  Install it (npm i -g @anthropic-ai/claude-code), open a new terminal, and re-run.')
+  return claude
+}
+
+export function writeJson(path, obj, secret = false) {
+  mkdirSync(OV_DIR, { recursive: true })
+  writeFileSync(path, JSON.stringify(obj, null, 2))
+  if (secret) chmodSafe(path, 0o600)
+}
+
+export function readConfig(slug) {
+  try { return JSON.parse(readFileSync(join(OV_DIR, `${slug}.json`), 'utf8')) } catch { return null }
+}
+
+export function configPath(slug) { return join(OV_DIR, `${slug}.json`) }
+export function mcpConfigPath(slug) { return join(OV_DIR, `${slug}-team.mcp.json`) }

package/src/watch.mjs

@@ -0,0 +1,226 @@
+// The OpenVisio autonomy watcher — an event-driven "warm" loop. Cheaply polls
+// /api/agent/inbox (no model) and pokes ONE persistent Claude Code stream-json
+// session with a cycle per new @mention / follow-up / ticket. Ported verbatim from
+// the shell installer so behaviour is identical — now shipped in the package rather
+// than written to disk from a pasted heredoc.
+
+import { spawn, spawnSync } from 'node:child_process'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { OV_DIR, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
+
+const CYCLE = 'Run one OpenVisio autonomy cycle.'
+const CYCLE_FAST = 'New chat activity in OpenVisio. Call poll_inbox once, then handle items in .mentions and .followUps ONLY (ignore .tasks/.claimable). Post AT MOST ONE reply per channel: if the same person sent several nudges (e.g. repeated @mentions or "status?"), answer them together in ONE post — never reply once per message. CRITICAL HONESTY RULE: your only tools are the openvisio-team chat/ticket tools. You CANNOT write code, read or clone a repo, or add entries to the API-testing/docs/sheets/flowchart tools — you have no tool for any of that. So NEVER say "On it" or "I will do it" for such work. If asked to do something you have no tool for, say plainly in one short message that you cannot do it yourself and what a human would need to do (or offer to file/track a ticket). Do not invent repo names or progress. Reply in 1-3 sentences, no summary; or react_message to dismiss. Then stop.'
+const CODE_FULL = 'Run one OpenVisio autonomy cycle. Call get_marching_orders and poll_inbox. You have file + Bash tools and a git repo at your working directory. For assigned tickets or mentions asking for real work: FIRST run "git checkout -B agent/work" to work on a branch, make the actual changes with Read/Edit/Write, run tests if present, then "git add -A && git commit -m ...". NEVER git push, merge, or touch main. Then comment_ticket with a short summary + the branch name (and move it to Done only if auto-move is on), and post a brief channel reply. If you truly cannot (missing repo/specs), say so plainly in one message — never fabricate progress or repo names.'
+const CODE_FAST = 'New chat activity in OpenVisio. Call poll_inbox, handle .mentions/.followUps ONLY, AT MOST ONE reply per channel. If a message asks for real work you can do in the git repo at your working directory, DO IT: "git checkout -B agent/work", make the changes with your file/Bash tools, commit locally (NEVER push or merge), then reply briefly with what you did + the branch name. If it needs a repo/spec you do not have, say so plainly — never fabricate progress or invent repo names. 1-3 sentences, no summary. Then stop.'
+
+const CODE_TOOLS = ['Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit', 'TodoWrite', 'Bash', 'mcp__openvisio-team__*']
+const DENY_TOOLS = ['Bash(git push:*)', 'Bash(git reset --hard:*)', 'Bash(git clean:*)', 'Bash(rm:*)', 'Bash(sudo:*)', 'Bash(chmod:*)', 'Bash(curl:*)', 'Bash(wget:*)', 'Bash(npm publish:*)', 'Bash(pnpm publish:*)', 'Bash(gh pr merge:*)', 'Bash(gh repo:*)']
+
+const FAST = 2500
+const SLOW = 6000
+const IDLE_AFTER = 60000
+const MAX_TURNS = 15
+const SESSION_IDLE_MS = 1200000
+
+export async function runWatch({ flags }) {
+  const slug = flags.name ? slugify(String(flags.name)) : null
+  const saved = slug ? readConfig(slug) : null
+  const host = stripSlash(flags.host || (saved && saved.host) || '')
+  const key = String(flags.key || (saved && saved.key) || '')
+  const claude = String(flags.claude || onPath('claude') || 'claude')
+  const mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
+  const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
+
+  if (!host || !key) fail('No saved connection for that agent.\n  Run `openvisio-agent connect <ovs_code> --host <url> --name <agent>` first, or pass --host and --key.')
+
+  if (flags.install) return installService({ slug: slug || 'openvisio', host, key, claude, mcpConfig, workdir })
+
+  return loop({ host, key, claude, mcpConfig, workdir })
+}
+
+// ── the warm loop ────────────────────────────────────────────────────────────
+function loop({ host, key, claude, mcpConfig, workdir }) {
+  const canCode = !!workdir
+  const fullPrompt = canCode ? CODE_FULL : CYCLE
+  const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
+
+  const seen = new Set()
+  let busy = false
+  let firstCheck = true
+  let lastNewAt = Date.now()
+
+  let child = null
+  let turnsThisSession = 0
+  let sessionStartedAt = 0
+  let resolveTurn = null
+
+  const log = (m) => process.stdout.write('[warm ' + new Date().toISOString() + '] ' + m + '\n')
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+  const settleTurn = (o) => { const r = resolveTurn; resolveTurn = null; if (r) r(o) }
+
+  function ensureSession() {
+    if (child && !child.killed) return
+    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig]
+    const args = canCode ? [...base, '--allowedTools', ...CODE_TOOLS, '--disallowedTools', ...DENY_TOOLS] : [...base, '--allowedTools', 'mcp__openvisio-team__*']
+    const c = spawn(claude, args, { cwd: workdir || undefined, stdio: ['pipe', 'pipe', 'inherit'] })
+    child = c
+    turnsThisSession = 0
+    sessionStartedAt = Date.now()
+    let localBuf = ''
+    c.stdout.on('data', (d) => {
+      if (c !== child) return
+      localBuf += d
+      let i
+      while ((i = localBuf.indexOf('\n')) >= 0) {
+        const line = localBuf.slice(0, i); localBuf = localBuf.slice(i + 1)
+        if (!line.trim()) continue
+        let o; try { o = JSON.parse(line) } catch { continue }
+        if (o.type === 'result') { log('cycle done (' + (o.subtype || 'ok') + ')'); settleTurn(o) }
+      }
+    })
+    c.on('exit', (code) => { if (c !== child) { log('old session exited ' + code); return } log('session exited ' + code); child = null; settleTurn({ type: 'result', subtype: 'exit' }) })
+    c.on('error', () => { if (c !== child) return; child = null; settleTurn({ type: 'result', subtype: 'error' }) })
+    log('warm session started')
+  }
+
+  function runCycle(prompt) {
+    return new Promise((resolve) => {
+      if (child && (turnsThisSession >= MAX_TURNS || Date.now() - sessionStartedAt > SESSION_IDLE_MS)) {
+        log('recycling session (turns=' + turnsThisSession + ')')
+        try { child.kill() } catch { /* already gone */ }
+        child = null
+      }
+      ensureSession()
+      turnsThisSession++
+      resolveTurn = resolve
+      try { child.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } }) + '\n') }
+      catch { settleTurn({ type: 'result', subtype: 'write-failed' }) }
+    })
+  }
+
+  async function check() {
+    const res = await fetch(host + '/api/agent/inbox', { headers: { authorization: 'Bearer ' + key } })
+    if (!res.ok) return { items: [], paused: false }
+    return await res.json()
+  }
+  async function quickReply() {
+    try {
+      const res = await fetch(host + '/api/agent/quick-reply', { method: 'POST', headers: { authorization: 'Bearer ' + key } })
+      if (!res.ok) return null
+      return await res.json()
+    } catch { return null }
+  }
+
+  async function run() {
+    log('up — warm watcher on ' + host + (canCode ? ' [code: ' + workdir + ']' : ''))
+    for (;;) {
+      let delay = FAST
+      try {
+        const res = busy ? { items: [], paused: false } : await check()
+        const items = Array.isArray(res.items) ? res.items : []
+        if (firstCheck && Array.isArray(res.items)) {
+          firstCheck = false
+          for (const i of items) if (i.startsWith('tk:') || i.startsWith('clm:')) seen.add(i)
+        }
+        if (res.paused) {
+          delay = SLOW
+        } else {
+          const fresh = items.filter((i) => !seen.has(i))
+          if (fresh.length && !busy) {
+            busy = true
+            const chatOnly = fresh.every((i) => i.startsWith('msg:') || i.startsWith('fu:'))
+            if (chatOnly) {
+              const q = await quickReply()
+              if (q && q.ok) {
+                log(fresh.length + ' new -> quick reply (' + (q.replied || 0) + ' posted)')
+                if (q.needsWork && canCode) { log('needs work -> full cycle'); await runCycle(fullPrompt) }
+              } else {
+                log(fresh.length + ' new -> fast reply (claude fallback)')
+                await runCycle(fastPrompt)
+              }
+            } else {
+              log(fresh.length + ' new item(s) -> full cycle' + (canCode ? ' [code]' : ''))
+              await runCycle(fullPrompt)
+            }
+            for (const i of items) seen.add(i)
+            if (seen.size > 500) { seen.clear(); for (const i of items) seen.add(i) }
+            busy = false
+            lastNewAt = Date.now()
+          } else {
+            delay = (Date.now() - lastNewAt > IDLE_AFTER) ? SLOW : FAST
+          }
+        }
+      } catch { delay = SLOW }
+      await sleep(delay)
+    }
+  }
+
+  return run()
+}
+
+// ── background service install (launchd / systemd) ───────────────────────────
+function installService({ slug, workdir }) {
+  const binPath = onPath('openvisio-agent')
+  if (!binPath) {
+    info('Installing openvisio-agent globally so the background service has a stable path…')
+    spawnSync('npm', ['i', '-g', 'openvisio-agent'], { stdio: 'inherit', shell: process.platform === 'win32' })
+  }
+  const bin = onPath('openvisio-agent') || 'openvisio-agent'
+  const nodeDir = dirname(process.execPath)
+  const claudeBin = onPath('claude')
+  const runPath = [nodeDir, claudeBin ? dirname(claudeBin) : '', '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean).join(':')
+  const args = ['watch', '--name', slug, ...(workdir ? ['--workdir', workdir] : [])]
+  mkdirSync(OV_DIR, { recursive: true })
+  const logFile = join(OV_DIR, `${slug}.log`)
+
+  if (process.platform === 'darwin') {
+    const label = `io.openvisio.${slug}`
+    const plist = join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`)
+    const progArgs = [bin, ...args].map((a) => `    <string>${a}</string>`).join('\n')
+    writeFileSync(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>
+${progArgs}
+  </array>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${runPath}</string></dict>
+  <key>KeepAlive</key><true/>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>${logFile}</string>
+  <key>StandardErrorPath</key><string>${logFile}</string>
+</dict></plist>
+`)
+    spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' })
+    const r = spawnSync('launchctl', ['load', plist], { stdio: 'inherit' })
+    if (r.status !== 0) fail('launchctl load failed — check the plist at ' + plist)
+    ok(`Live in the background, auto-starts at login. Logs:  tail -f ${logFile}`)
+  } else if (process.platform === 'win32') {
+    fail('Background install isn\'t supported on Windows yet. Run it in the foreground:\n  openvisio-agent watch --name ' + slug)
+  } else {
+    const dir = join(homedir(), '.config', 'systemd', 'user')
+    mkdirSync(dir, { recursive: true })
+    const unit = join(dir, `openvisio-${slug}.service`)
+    const execStart = [bin, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')
+    writeFileSync(unit, `[Unit]
+Description=OpenVisio agent watcher (${slug})
+After=network-online.target
+
+[Service]
+Environment=PATH=${runPath}
+ExecStart=${execStart}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`)
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' })
+    const r = spawnSync('systemctl', ['--user', 'enable', '--now', `openvisio-${slug}.service`], { stdio: 'inherit' })
+    spawnSync('loginctl', ['enable-linger', process.env.USER || ''], { stdio: 'ignore' })
+    if (r.status !== 0) fail('systemctl enable failed — is this a systemd user session?')
+    ok(`Live in the background, auto-starts at login. Logs:  journalctl --user -u openvisio-${slug} -f`)
+  }
+}