@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/platform/linux.ts

@@ -0,0 +1,139 @@
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type {
+  NotificationKind,
+  NotifierCapability,
+  NotifierTestResult,
+  Platform,
+  ProcessInfo,
+  ScheduledJob,
+  ScheduledJobStatus,
+} from './types';
+import { existsSync } from 'node:fs';
+import {
+  installSystemdJob,
+  removeSystemdJob,
+  systemdJobStatus,
+} from './systemd-user';
+import { psProcesses } from './ps';
+
+export class LinuxPlatform implements Platform {
+  readonly name = 'linux' as const;
+  readonly label = 'Linux';
+
+  opencodeDir(): string {
+    const base =
+      process.env['XDG_CONFIG_HOME']?.trim() || join(homedir(), '.config');
+    return join(base, 'opencode');
+  }
+
+  cacheDir(): string {
+    const base =
+      process.env['XDG_CACHE_HOME']?.trim() || join(homedir(), '.cache');
+    return base;
+  }
+
+  globalBinDir(): string {
+    return join(homedir(), '.local/bin');
+  }
+
+  canBuildSwiftNotifier(): boolean {
+    return false;
+  }
+
+  shellRcFiles(): readonly string[] {
+    const home = homedir();
+    return [
+      join(home, '.bashrc'),
+      join(home, '.bash_profile'),
+      join(home, '.zshrc'),
+      join(home, '.config/fish/config.fish'),
+    ];
+  }
+
+  notifierCapabilities(): NotifierCapability {
+    return {
+      native: true,
+      sounds: false,
+      clickToFocus: false,
+      reason:
+        'Linux uses notify-send (no sounds, no click-to-focus); the macOS OpenCodeNotifier app is macOS-only.',
+    };
+  }
+
+  async postNotification(input: {
+    title: string;
+    message: string;
+    kind: NotificationKind;
+  }): Promise<NotifierTestResult> {
+    void input.kind;
+    const candidates: ReadonlyArray<{ cmd: string; args: string[] }> = [
+      { cmd: 'notify-send', args: [input.title, input.message] },
+      { cmd: 'zenity', args: ['--notification', `--text=${input.message}`] },
+    ];
+    for (const candidate of candidates) {
+      const r = spawnSync(candidate.cmd, candidate.args, { stdio: 'ignore' });
+      if (r.status === 0) {
+        return { ok: true, detail: `posted via ${candidate.cmd}` };
+      }
+    }
+    return {
+      ok: false,
+      detail: 'no notifier found (install libnotify: notify-send)',
+    };
+  }
+
+  isNotifierDaemonRunning(): boolean {
+    return false;
+  }
+
+  restartNotifierDaemon(): void {
+    // No daemon on Linux — no-op.
+  }
+
+  availableSystemSounds(): string[] {
+    return [];
+  }
+
+  async playSystemSound(name: string): Promise<NotifierTestResult> {
+    void name;
+    return {
+      ok: false,
+      detail: 'sounds unsupported on Linux (notify-send has no sound API)',
+    };
+  }
+
+  listProcesses(): ProcessInfo[] | null {
+    return psProcesses();
+  }
+
+  tailscaleAppBinaries(): readonly string[] {
+    return ['/usr/bin/tailscale', '/usr/sbin/tailscale'].filter((p) =>
+      existsSync(p)
+    );
+  }
+
+  vscodeSettingsPath(): string | null {
+    const base =
+      process.env['XDG_CONFIG_HOME']?.trim() || join(homedir(), '.config');
+    return join(base, 'Code/User/settings.json');
+  }
+
+  vscodeCliBinaries(): readonly string[] {
+    return ['/usr/share/code/bin/code'].filter((p) => existsSync(p));
+  }
+
+  installScheduledJob(job: ScheduledJob): NotifierTestResult {
+    return installSystemdJob(job);
+  }
+
+  removeScheduledJob(label: string): NotifierTestResult {
+    return removeSystemdJob(label);
+  }
+
+  scheduledJobStatus(label: string): ScheduledJobStatus {
+    return systemdJobStatus(label);
+  }
+}

package/src/platform/ps.ts

@@ -0,0 +1,45 @@
+import { spawnSync } from 'node:child_process';
+
+import type { ProcessInfo } from './types';
+
+// `args` goes last because it is the only column that may contain spaces.
+const PS_ARGS = [
+  '-A',
+  '-ww',
+  '-o',
+  'pid=,ppid=,pgid=,uid=,rss=,pcpu=,stat=,args=',
+];
+const ROW =
+  /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+([\d.]+)\s+(\S+)\s+(.*)$/;
+const PS_MAX_BUFFER = 64 * 1024 * 1024;
+
+export function parsePsOutput(stdout: string): ProcessInfo[] {
+  const rows: ProcessInfo[] = [];
+  for (const line of stdout.split('\n')) {
+    const m = ROW.exec(line);
+    if (m === null) continue;
+    rows.push({
+      pid: Number(m[1]),
+      ppid: Number(m[2]),
+      pgid: Number(m[3]),
+      uid: Number(m[4]),
+      rssKb: Number(m[5]),
+      cpu: Number(m[6]),
+      state: m[7] ?? '',
+      command: (m[8] ?? '').trim(),
+    });
+  }
+  return rows;
+}
+
+/** One `ps` call for the whole table (BSD + procps compatible). */
+export function psProcesses(): ProcessInfo[] | null {
+  const r = spawnSync('ps', PS_ARGS, {
+    encoding: 'utf8',
+    maxBuffer: PS_MAX_BUFFER,
+    // Force `.` decimals in pcpu regardless of the user's locale.
+    env: { ...process.env, LC_ALL: 'C' },
+  });
+  if (r.status !== 0 || typeof r.stdout !== 'string') return null;
+  return parsePsOutput(r.stdout);
+}

package/src/platform/resource-verify.ts

@@ -0,0 +1,132 @@
+import policy from '../../ansible/ubuntu/policy.json';
+import type { Check, Runner } from '../types';
+
+const AGENT_DROP_IN =
+  '/etc/systemd/user/t3code-.scope.d/60-personal-fleet.conf';
+const GUARDS = [
+  'systemd-oomd.service',
+  'personal-fleet-disk-guard.service',
+  'personal-fleet-disk-gc.timer',
+];
+const MIB = 1024 * 1024;
+const FLOOR_MIB = policy.resourceSafety.diskGuardFloorMiB;
+
+/** A failure code and remedy, or undefined when the probe passes. */
+type Probe = (run: Runner) => Promise<[string, string] | undefined>;
+
+const guardsRunning: Probe = async (run) => {
+  for (const unit of GUARDS) {
+    const active = await run(['systemctl', 'is-active', unit]);
+    if (active.stdout.trim() !== 'active')
+      return [
+        'RESOURCE_GUARD_INACTIVE',
+        `${unit} is not running. Reapply fleet-sync; runaway memory or disk use is unguarded until then.`,
+      ];
+  }
+  return undefined;
+};
+
+const memoryReserved: Probe = async (run) => {
+  const show = (property: string, unit: string) =>
+    run(['systemctl', 'show', `--property=${property}`, '--', unit]);
+  const user = await show('MemoryMax', 'user.slice');
+  const root = await show('ManagedOOMSwap', '-.slice');
+  const ok =
+    /^MemoryMax=\d+$/m.test(user.stdout) &&
+    /^ManagedOOMSwap=kill$/m.test(root.stdout);
+  return ok
+    ? undefined
+    : [
+        'MEMORY_RESERVE_MISSING',
+        'User workloads are not capped below physical memory, or swap exhaustion is unmanaged. Reapply fleet-sync.',
+      ];
+};
+
+const agentsBounded: Probe = async (run) =>
+  (await run(['test', '-f', AGENT_DROP_IN])).ok
+    ? undefined
+    : [
+        'AGENT_MEMORY_LIMIT_MISSING',
+        'T3 agent scopes have no per-agent memory limit. Reapply fleet-sync; new agents pick it up without restarts.',
+      ];
+
+const swapActive: Probe = async (run) => {
+  // /proc/swaps, not swapon: /usr/sbin is not on the remote worker PATH.
+  const swaps = await run(['cat', '/proc/swaps']);
+  return swaps.ok && swaps.stdout.trim().split('\n').length > 1
+    ? undefined
+    : [
+        'SWAP_MISSING',
+        'No swap is active. Reapply fleet-sync with enough free disk for the swap file.',
+      ];
+};
+
+const diskAboveFloor =
+  (path: string): Probe =>
+  async (run) => {
+    const df = await run(['df', '--output=avail', '-B1', path]);
+    const free = Number(df.stdout.trim().split('\n').at(-1));
+    if (!df.ok || !Number.isSafeInteger(free))
+      return ['DISK_FREE_UNREADABLE', `Free space on ${path} is unreadable.`];
+    if (free >= FLOOR_MIB * MIB) return undefined;
+    return [
+      'DISK_FREE_BELOW_FLOOR',
+      `${path} has ${Math.floor(free / MIB)} MiB free, under the ${FLOOR_MIB} MiB floor. The disk GC already removed idle build output and caches; remove stale worktrees or data, or run "sudo systemctl start personal-fleet-disk-gc.service" and read its journal.`,
+    ];
+  };
+
+/** Free space cannot show this: /tmp is RAM-backed with a per-user quota, so a
+ * write fails while the filesystem still reports room. Probe a real 1 MiB write.
+ */
+const tmpWritable: Probe = async (run) =>
+  (
+    await run([
+      'sh',
+      '-c',
+      'f=$(mktemp /tmp/personal-fleet-probe.XXXXXX) || exit 1; head -c 1048576 /dev/zero >"$f"; s=$?; rm -f -- "$f"; exit "$s"',
+    ])
+  ).ok
+    ? undefined
+    : [
+        'TMP_QUOTA_EXHAUSTED',
+        'This user cannot write to /tmp (full, or its per-user quota is used up), so agents and builds fail. The guard never deletes files; remove stale caches and scratch directories under /tmp.',
+      ];
+
+/** Measured memory and disk safety on an Ubuntu worker: the running managers,
+ * not the files Ansible wrote. Free space below the guard floor fails because
+ * what is left after the disk GC is work a person must decide about.
+ */
+export async function verifyResourceSafety(
+  home: string,
+  run: Runner
+): Promise<Check[]> {
+  const probes = [
+    guardsRunning,
+    memoryReserved,
+    agentsBounded,
+    swapActive,
+    diskAboveFloor('/'),
+    diskAboveFloor(home),
+    tmpWritable,
+  ];
+  for (const probe of probes) {
+    const failure = await probe(run);
+    if (failure)
+      return [
+        {
+          id: 'ubuntu:resource-safety',
+          status: 'fail',
+          summary: failure[0],
+          remedy: { action: failure[1] },
+        },
+      ];
+  }
+  return [
+    {
+      id: 'ubuntu:resource-safety',
+      status: 'pass',
+      summary:
+        'systemd-oomd, the disk guard and the disk GC timer are running, user workloads are capped below physical memory, T3 agents have per-agent limits, swap is active, free disk is above the guard floor and /tmp is writable.',
+    },
+  ];
+}

package/src/platform/systemd-user.ts

@@ -0,0 +1,95 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type {
+  NotifierTestResult,
+  ScheduledJob,
+  ScheduledJobStatus,
+} from './types';
+
+function unitDir(): string {
+  const base =
+    process.env['XDG_CONFIG_HOME']?.trim() || join(homedir(), '.config');
+  return join(base, 'systemd/user');
+}
+
+function quote(arg: string): string {
+  return /^[\w@%+=:,./-]+$/.test(arg)
+    ? arg
+    : `"${arg.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+/** systemd user service + timer for a periodic job. Pure — unit-tested. */
+export function systemdUnits(job: ScheduledJob): {
+  service: string;
+  timer: string;
+} {
+  const env = Object.entries(job.env).map(
+    ([k, v]) => `Environment=${quote(`${k}=${v}`)}`
+  );
+  const service = [
+    '[Unit]',
+    `Description=${job.label}`,
+    '',
+    '[Service]',
+    'Type=oneshot',
+    'Nice=10',
+    ...env,
+    `ExecStart=${job.command.map(quote).join(' ')}`,
+    `StandardOutput=append:${join(job.logDir, `${job.label}.out.log`)}`,
+    `StandardError=append:${join(job.logDir, `${job.label}.err.log`)}`,
+    '',
+  ].join('\n');
+  const timer = [
+    '[Unit]',
+    `Description=${job.label} every ${job.intervalSeconds}s`,
+    '',
+    '[Timer]',
+    'OnBootSec=60',
+    `OnUnitActiveSec=${job.intervalSeconds}`,
+    '',
+    '[Install]',
+    'WantedBy=timers.target',
+    '',
+  ].join('\n');
+  return { service, timer };
+}
+
+function systemctl(args: readonly string[]): { ok: boolean; out: string } {
+  const r = spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8' });
+  return {
+    ok: r.status === 0,
+    out: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim(),
+  };
+}
+
+export function installSystemdJob(job: ScheduledJob): NotifierTestResult {
+  const dir = unitDir();
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(job.logDir, { recursive: true });
+  const { service, timer } = systemdUnits(job);
+  writeFileSync(join(dir, `${job.label}.service`), service);
+  writeFileSync(join(dir, `${job.label}.timer`), timer);
+  systemctl(['daemon-reload']);
+  const r = systemctl(['enable', '--now', `${job.label}.timer`]);
+  return r.ok
+    ? { ok: true, detail: `systemd user timer ${job.label}.timer` }
+    : { ok: false, detail: `systemctl --user enable failed: ${r.out}` };
+}
+
+export function removeSystemdJob(label: string): NotifierTestResult {
+  systemctl(['disable', '--now', `${label}.timer`]);
+  rmSync(join(unitDir(), `${label}.timer`), { force: true });
+  rmSync(join(unitDir(), `${label}.service`), { force: true });
+  systemctl(['daemon-reload']);
+  return { ok: true, detail: `removed systemd user timer ${label}` };
+}
+
+export function systemdJobStatus(label: string): ScheduledJobStatus {
+  const r = systemctl(['is-active', `${label}.timer`]);
+  return r.ok
+    ? { supported: true, installed: true, detail: 'timer active' }
+    : { supported: true, installed: false, detail: r.out || 'not installed' };
+}

package/src/platform/t3-policy.ts

@@ -0,0 +1,137 @@
+import { runAnsible } from './ansible';
+import { desired } from '../t3/desired';
+import policy from '../../ansible/ubuntu/t3/policy.json';
+import { basename, dirname, join, resolve } from 'node:path';
+import { rename, rm, symlink } from 'node:fs/promises';
+import { userInfo } from 'node:os';
+import type { Runner, Check } from '../types';
+
+export async function stageT3Policy(
+  root: string,
+  executable: string,
+  run: Runner,
+  node: string
+): Promise<Check> {
+  const instances = await desired(
+    resolve(root, 'agents/t3.json'),
+    await stableWorkspace(root),
+    node
+  );
+  const user = userInfo();
+  const document = {
+    ...policy,
+    settings: Object.fromEntries(
+      Object.entries(instances).map(([id, value]) => [
+        `providerInstances.${id}`,
+        { value, locked: true },
+      ])
+    ),
+  };
+  const result = await runAnsible(run, 't3-policy.yml', {
+    cwd: resolve(root, 'ansible/ubuntu'),
+    input: JSON.stringify({
+      t3_executable: executable,
+      t3_policy_document: document,
+      development_user: user.username,
+      development_uid: user.uid,
+    }),
+    timeoutMs: 120_000,
+  });
+  return {
+    id: 't3:policy-staged',
+    status: result.ok ? 'pass' : 'fail',
+    summary: result.ok
+      ? 'Native T3 policy validated and staged; a running T3 that had not loaded it was restarted.'
+      : 'T3_POLICY_STAGE_FAILED',
+    remedy: {
+      action:
+        'Review any existing administrator policy and the pinned native validation result. No live settings database or user state is overwritten.',
+    },
+  };
+}
+export async function verifyT3Policy(
+  executable: string,
+  run: Runner,
+  pause: () => Promise<void> = () =>
+    new Promise((done) => setTimeout(done, 1000))
+): Promise<Check> {
+  // A newly started native server can be active before loading its policy:
+  // bounded, read-only observation.
+  let loaded = false;
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const result = await run([executable, 'policy', 'show'], {
+      timeoutMs: 5000,
+    });
+    loaded = result.ok && /loaded this policy\.\s*$/.test(result.stdout);
+    if (loaded) break;
+    if (attempt < 5) await pause();
+  }
+  return {
+    id: 't3:policy-loaded',
+    status: loaded ? 'pass' : 'fail',
+    summary: loaded
+      ? 'Running T3 server confirms it loaded the installed managed policy.'
+      : 'T3_POLICY_RESTART_PENDING',
+    remedy: {
+      action:
+        'T3 did not load the installed policy after a restart. Inspect systemctl --user status t3code-desktop.service on the node, then rerun fleet-sync.',
+    },
+  };
+}
+
+/** Summary when the policy play restarted T3: its manager link reconnects next. */
+export const T3_RESTARTED_SUMMARY =
+  'T3 was restarted to load the new managed policy; the running server confirms it.';
+
+/** `t3-policy.yml` restarts a running T3 that has not loaded the staged policy
+ * (ending its running turns), so every node offers the same providers after
+ * every sync. This measures the outcome; `restarted` says whether the app
+ * restarted during this sync and so needs time to reconnect.
+ */
+export async function loadedT3Policy(
+  executable: string,
+  run: Runner,
+  options: { restarted: boolean; pause?: () => Promise<void> }
+): Promise<Check> {
+  // A restarted desktop app takes a few seconds to come back with its server.
+  const check = await verifyT3Policy(
+    executable,
+    run,
+    options.pause ??
+      (() =>
+        new Promise((done) =>
+          setTimeout(done, options.restarted ? 5000 : 1000)
+        ))
+  );
+  if (check.status !== 'pass')
+    return { ...check, summary: 'T3_POLICY_RESTART_FAILED' };
+  return options.restarted
+    ? { ...check, summary: T3_RESTARTED_SUMMARY }
+    : check;
+}
+
+/** Fleet revisions live at .../fleet/revisions/<sha> (workers) or
+ * .../fleet/manager-runs/<sha> (the manager). Point .../fleet/current at the
+ * applied revision and reference it from T3, so provider settings (and the T3
+ * restart a policy needs) change only when they really change, not on every
+ * new commit, and never name a checkout that is later pruned. Other checkouts
+ * are used as-is.
+ */
+export async function stableWorkspace(root: string): Promise<string> {
+  const current = stablePath(root);
+  if (current === root) return root;
+  const revisions = dirname(resolve(root));
+  const staged = `${current}.${process.pid}`;
+  await rm(staged, { force: true });
+  await symlink(join(basename(revisions), basename(resolve(root))), staged);
+  await rename(staged, current);
+  return current;
+}
+
+/** Where `stableWorkspace` points for this checkout, without moving it. */
+export function stablePath(root: string): string {
+  const revisions = dirname(resolve(root));
+  return ['revisions', 'manager-runs'].includes(basename(revisions))
+    ? join(dirname(revisions), 'current')
+    : root;
+}

package/src/platform/t3-route.ts

@@ -0,0 +1,68 @@
+import { inspectRoute } from '../monitoring/hub';
+import { parseTailnet } from '../tailscale';
+import type { Check, Runner } from '../types';
+
+/** The one place the route is declared; `t3-route.yml` receives it. */
+export const T3_ROUTE = { port: '443', proxy: 'http://127.0.0.1:3773' };
+const target = T3_ROUTE;
+/** `t3-route.yml` publishes the route when port 443 has no owner; this refuses
+ * a conflicting owner beforehand and measures the result. Stock Serve persists
+ * independently of T3 startup, so a temporarily unavailable VPN does not
+ * prevent the local development server from starting. No Funnel, pairing,
+ * firewall change or service restart.
+ */
+export async function convergeT3Route(
+  run: Runner,
+  publish: () => Promise<boolean>
+): Promise<Check[]> {
+  const dns = await selfDns(run);
+  if (!dns) return pending('T3_PRIVATE_IDENTITY_REQUIRED');
+  const url = 'https://' + dns;
+  const before = await run(['tailscale', 'serve', 'status', '--json']);
+  if (!before.ok) return pending('T3_PRIVATE_ROUTE_UNVERIFIED');
+  const route = inspectRoute(before.stdout, url, target);
+  if (Array.isArray(route)) return pending('T3_PRIVATE_ROUTE_CONFLICT');
+  if (!route && !(await publish())) return pending('T3_PRIVATE_ROUTE_REQUIRED');
+  const after = route
+    ? before
+    : await run(['tailscale', 'serve', 'status', '--json']);
+  if (!after.ok || inspectRoute(after.stdout, url, target) !== true)
+    return pending('T3_PRIVATE_ROUTE_UNVERIFIED');
+  return [
+    {
+      id: 't3:private-route',
+      status: 'pass',
+      summary:
+        'Private HTTPS Serve route observed at ' +
+        url +
+        '; manager reachability and paired tool execution remain separate checks.',
+    },
+  ];
+}
+function pending(code: string): Check[] {
+  return [
+    {
+      id: 't3:private-route',
+      status: 'fail',
+      summary: code,
+      remedy: {
+        action:
+          'Inspect this node’s Tailscale identity, HTTPS capability and port 443 Serve ownership. Preserve existing routes; never reset Serve or enable Funnel. Pair using the native T3 client after a separate manager connection succeeds.',
+      },
+    },
+  ];
+}
+
+async function selfDns(run: Runner): Promise<string | null> {
+  const status = await run(['tailscale', 'status', '--json']);
+  let dns: string | undefined;
+  try {
+    if (status.ok)
+      dns = parseTailnet(JSON.parse(status.stdout)).computers.find(
+        (peer) => peer.self
+      )?.dns;
+  } catch {
+    /* No auth responses or raw status in reports. */
+  }
+  return dns && /^[a-z0-9.-]+\.ts\.net$/.test(dns) ? dns : null;
+}

package/src/platform/t3-service.ts

@@ -0,0 +1,75 @@
+import type { Runner, Check } from '../types';
+
+/** The user unit that runs the pinned desktop app (UI and embedded server). */
+export const T3_DESKTOP_UNIT = 't3code-desktop.service';
+
+/** Workers run one T3 process: the desktop app, started with the auto-login
+ * graphical session. `t3-desktop.yml` installs it, retires the former headless
+ * server and starts the app; this only refuses a foreign launcher beforehand
+ * and measures the result afterwards.
+ */
+export async function convergeT3Service(
+  artifact: { path: string; version: string },
+  run: Runner,
+  prepare: () => Promise<Check[]> = async () => [],
+  install: () => Promise<boolean> = async () => true
+): Promise<Check[]> {
+  const existing = await run(['t3', '--version']);
+  if (conflictingVersion(existing, artifact.version))
+    return pending(
+      'T3_EXECUTABLE_OWNER_CONFLICT',
+      'The existing T3 launcher has a different version. Review the pinned release; preserve its application data and active sessions.'
+    );
+  const preparation = await prepare();
+  if (preparation.length) return preparation;
+  if (!(await install()))
+    return pending(
+      'T3_DESKTOP_INSTALL_FAILED',
+      'Inspect the t3-desktop.yml Ansible output (package download, apt, GDM auto-login, user unit). T3 data in ~/.t3 is untouched.'
+    );
+  const active = await userctl(run, 'is-active', T3_DESKTOP_UNIT);
+  const enabled = await userctl(run, 'is-enabled', T3_DESKTOP_UNIT);
+  if (!active.ok || !enabled.ok)
+    return pending(
+      'T3_DESKTOP_STOPPED',
+      `The desktop app needs the auto-login graphical session. Reboot or log in on the machine, then inspect journalctl --user -u ${T3_DESKTOP_UNIT}; ~/.t3 is preserved.`
+    );
+  return [
+    {
+      id: 't3:service',
+      status: 'pass',
+      summary:
+        'Pinned T3 desktop app is enabled for the auto-login session and running. Private routing, policy and pairing remain separate checks.',
+    },
+  ];
+}
+
+/** When the desktop app last started; changes exactly when it restarts. */
+export async function t3StartedAt(run: Runner): Promise<string> {
+  const shown = await run([
+    'systemctl',
+    '--user',
+    'show',
+    '--property=ActiveEnterTimestampMonotonic',
+    '--value',
+    T3_DESKTOP_UNIT,
+  ]);
+  return shown.ok ? shown.stdout.trim() : '';
+}
+
+function userctl(run: Runner, verb: string, unit: string) {
+  return run(['systemctl', '--user', verb, unit]);
+}
+
+function pending(code: string, action: string): Check[] {
+  return [
+    { id: 't3:service', status: 'fail', summary: code, remedy: { action } },
+  ];
+}
+
+function conflictingVersion(
+  result: { ok: boolean; stdout: string },
+  version: string
+): boolean {
+  return result.ok && result.stdout.trim() !== `t3 v${version}`;
+}