@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/utils/server/source_server_workspace_deps.test.mjs

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { ensureSourceServerWorkspacePackagesBuilt, spawnSourceServerScript } from './source_server_workspace_deps.mjs';
+
+test('source server admission delegates declaration freshness to the canonical workspace owner', async () => {
+  const calls = [];
+  const result = await ensureSourceServerWorkspacePackagesBuilt(
+    { runtimeBackedStart: false, serverDir: '/repo/apps/server', env: { TEST_ENV: '1' }, quiet: true },
+    {
+      ensureWorkspacePackagesBuiltForComponentImpl: async (dir, options) => {
+        calls.push({ dir, options });
+        return { ok: true, built: [], skipped: ['current'] };
+      },
+    },
+  );
+
+  assert.deepEqual(calls, [{ dir: '/repo/apps/server', options: { quiet: true, env: { TEST_ENV: '1' } } }]);
+  assert.deepEqual(result, {
+    ran: true,
+    reason: 'source-server',
+    result: { ok: true, built: [], skipped: ['current'] },
+  });
+});
+
+test('runtime snapshot server admission does not inspect mutable workspace declarations', async () => {
+  let called = false;
+  const result = await ensureSourceServerWorkspacePackagesBuilt(
+    { runtimeBackedStart: true, serverDir: '/repo/apps/server', env: {} },
+    { ensureWorkspacePackagesBuiltForComponentImpl: async () => { called = true; } },
+  );
+
+  assert.equal(called, false);
+  assert.deepEqual(result, { ran: false, reason: 'runtime-backed' });
+});
+
+test('source server spawn admits declarations once before launching', async () => {
+  const calls = [];
+  const child = { pid: 1234 };
+  const result = await spawnSourceServerScript(
+    { label: 'server', serverDir: '/repo/apps/server', script: 'start', env: { PORT: '34567' }, quiet: true },
+    {
+      ensureWorkspacePackagesBuiltForComponentImpl: async (dir, options) => calls.push(['workspace', dir, options]),
+      pmSpawnScriptImpl: async (options) => {
+        calls.push(['spawn', options]);
+        return child;
+      },
+    },
+  );
+
+  assert.equal(result, child);
+  assert.deepEqual(calls, [
+    ['workspace', '/repo/apps/server', { quiet: true, env: { PORT: '34567' } }],
+    ['spawn', { label: 'server', dir: '/repo/apps/server', script: 'start', env: { PORT: '34567' } }],
+  ]);
+});
+
+test('source server spawn fails closed before launch when declaration admission fails', async () => {
+  let spawned = false;
+  await assert.rejects(
+    () => spawnSourceServerScript(
+      { label: 'server', serverDir: '/repo/apps/server', script: 'start', env: {} },
+      {
+        ensureWorkspacePackagesBuiltForComponentImpl: async () => { throw new Error('stale declaration rebuild failed'); },
+        pmSpawnScriptImpl: async () => { spawned = true; },
+      },
+    ),
+    /stale declaration rebuild failed/,
+  );
+  assert.equal(spawned, false);
+});

package/scripts/utils/server/urls.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 
-import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getStackName, resolveActiveStackEnvFilePath } from '../paths/paths.mjs';
 import { preferStackLocalhostUrl } from '../paths/localhost_host.mjs';
 import { resolvePublicServerUrl } from '../../tailscale.mjs';
 import { resolveServerPortFromEnv } from './port.mjs';
@@ -9,8 +9,7 @@ import { normalizeUrlNoTrailingSlash } from '../net/url.mjs';
 function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
   try {
     const envPath =
-      (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim() ||
-      resolveStackEnvPath(stackName).envPath;
+      resolveActiveStackEnvFilePath(stackName, env);
     if (!envPath || !existsSync(envPath)) return false;
     const raw = readFileSync(envPath, 'utf-8');
     return /^HAPPIER_PUBLIC_SERVER_URL=/m.test(raw) || /^HAPPIER_STACK_SERVER_URL=/m.test(raw);
@@ -22,8 +21,7 @@ function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
 function stackEnvExplicitlySetsWebappUrl({ env, stackName }) {
   try {
     const envPath =
-      (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim() ||
-      resolveStackEnvPath(stackName).envPath;
+      resolveActiveStackEnvFilePath(stackName, env);
     if (!envPath || !existsSync(envPath)) return false;
     const raw = readFileSync(envPath, 'utf-8');
     return /^HAPPIER_WEBAPP_URL=/m.test(raw);

package/scripts/utils/server/urls.test.mjs

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -49,3 +49,24 @@ test('getPublicServerUrlEnvOverride falls back to HAPPIER_STACK_SERVER_URL when
   assert.equal(out.envPublicUrl, 'https://stack-share.example.test');
   assert.equal(out.publicServerUrl, 'https://stack-share.example.test');
 });
+
+test('getPublicServerUrlEnvOverride expands ~/ explicit env file overrides against HOME', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-server-urls-'));
+  const homeDir = join(dir, 'home');
+  const envPath = join(homeDir, '.happier', 'stacks', 'dev', 'env');
+  await mkdir(join(homeDir, '.happier', 'stacks', 'dev'), { recursive: true });
+  await writeFile(envPath, 'HAPPIER_STACK_SERVER_URL=https://stack-share.example.test\n', 'utf-8');
+
+  const out = getPublicServerUrlEnvOverride({
+    env: {
+      HOME: homeDir,
+      HAPPIER_STACK_STACK: 'dev',
+      HAPPIER_STACK_ENV_FILE: '~/.happier/stacks/dev/env',
+      HAPPIER_STACK_SERVER_URL: 'https://stack-share.example.test',
+    },
+    serverPort: 3005,
+  });
+
+  assert.equal(out.envPublicUrl, 'https://stack-share.example.test');
+  assert.equal(out.publicServerUrl, 'https://stack-share.example.test');
+});

package/scripts/utils/server/validate.mjs

@@ -1,6 +1,3 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
 export function detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir }) {
   // Repo-only model: server flavors share the same monorepo checkout/worktree.
   // The previous "mismatch" check was specific to the legacy multi-repo components layout.
@@ -16,45 +13,9 @@ export function assertServerComponentDirMatches({ rootDir, serverComponentName,
   void serverDir;
 }
 
-function detectPrismaProvider(schemaText) {
-  // Best-effort parse of:
-  // datasource db { provider = "sqlite" ... }
-  const m = schemaText.match(/datasource\s+db\s*\{[\s\S]*?\bprovider\s*=\s*\"([a-zA-Z0-9_-]+)\"/m);
-  return m?.[1] ?? '';
-}
-
 export function assertServerPrismaProviderMatches({ serverComponentName, serverDir }) {
-  const schemaPath = join(serverDir, 'prisma', 'schema.prisma');
-
-  let schemaText = '';
-  try {
-    schemaText = readFileSync(schemaPath, 'utf-8');
-  } catch {
-    // If it doesn't exist, skip validation; not every server component necessarily uses Prisma.
-    return;
-  }
-
-  const provider = detectPrismaProvider(schemaText);
-  if (!provider) return;
-
-  // Happier server flavors share a single server package in the monorepo.
-  // Both the full server and the current light server use a Postgres schema (light runs via embedded PGlite).
-  if (serverComponentName === 'happier-server-light') {
-    if (provider !== 'postgresql') {
-      throw new Error(
-        `[server] happier-server-light expects Prisma datasource provider \"postgresql\", but found \"${provider}\" in:\n` +
-          `- ${schemaPath}\n` +
-          `Fix: point happier-server-light at a checkout that includes the current light flavor implementation (PGlite) and uses the Postgres schema.`
-      );
-    }
-    return;
-  }
-
-  if (serverComponentName === 'happier-server' && provider === 'sqlite') {
-    throw new Error(
-      `[server] happier-server expects Prisma datasource provider \"postgresql\", but found \"sqlite\" in:\n` +
-        `- ${schemaPath}\n` +
-        `Fix: point happier-server at a checkout that uses the Postgres schema.`
-    );
-  }
+  // Database provider is runtime configuration shared by both presets. The
+  // repository intentionally contains multiple Prisma schemas.
+  void serverComponentName;
+  void serverDir;
 }

package/scripts/utils/server/validate.test.mjs

@@ -48,17 +48,17 @@ test('assertServerPrismaProviderMatches accepts happier-server-light when schema
   });
 });
 
-test('assertServerPrismaProviderMatches rejects happier-server-light when schema.prisma is sqlite', async () => {
+test('assertServerPrismaProviderMatches does not infer light runtime provider from a preset schema', async () => {
   await withValidateDir(async (dir) => {
     await writeSchemas({ dir, schemaPrisma: SQLITE_SCHEMA, schemaSqlitePrisma: SQLITE_SCHEMA });
-    assert.throws(() => assertServerPrismaProviderMatches({ serverComponentName: 'happier-server-light', serverDir: dir }));
+    assert.doesNotThrow(() => assertServerPrismaProviderMatches({ serverComponentName: 'happier-server-light', serverDir: dir }));
   });
 });
 
-test('assertServerPrismaProviderMatches rejects happier-server when schema.prisma is sqlite', async () => {
+test('assertServerPrismaProviderMatches does not infer full runtime provider from a preset schema', async () => {
   await withValidateDir(async (dir) => {
     await writeSchemas({ dir, schemaPrisma: SQLITE_SCHEMA, schemaSqlitePrisma: null });
-    assert.throws(() => assertServerPrismaProviderMatches({ serverComponentName: 'happier-server', serverDir: dir }));
+    assert.doesNotThrow(() => assertServerPrismaProviderMatches({ serverComponentName: 'happier-server', serverDir: dir }));
   });
 });
 

package/scripts/utils/service/archive_service_lifecycle.mjs

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import {
+  inspectServiceRegistration,
+  resolveServiceBackend,
+  resolveServiceDefinitionPath,
+} from '@happier-dev/cli-common/service';
+
+export function resolveStackServiceDefinitionCandidates({ platform = process.platform, homeDir, label } = {}) {
+  const home = String(homeDir ?? '').trim();
+  const serviceLabel = String(label ?? '').trim();
+  if (!home) throw new Error('[stack] archive service cleanup requires a home directory');
+  if (!serviceLabel) throw new Error('[stack] archive service cleanup requires a service label');
+
+  const modes = platform === 'darwin' ? ['user'] : platform === 'linux' || platform === 'win32' ? ['user', 'system'] : null;
+  if (!modes) throw new Error(`[stack] archive service cleanup is unsupported on platform: ${platform}`);
+  return modes.map((mode) => ({
+    mode,
+    path: resolveServiceDefinitionPath({ platform, mode, homeDir: home, label: serviceLabel }),
+  }));
+}
+
+export async function disableInstalledStackServicesBeforeArchive({
+  rootDir,
+  stackName,
+  platform = process.platform,
+  homeDir,
+  label = stackName === 'main' ? 'dev.happier.stack' : `dev.happier.stack.${stackName}`,
+  definitionCandidates = resolveStackServiceDefinitionCandidates({ platform, homeDir, label }),
+  definitionExists = (path) => existsSync(path),
+  inspectRegistration = ({ mode }) => inspectServiceRegistration({
+    backend: resolveServiceBackend({ platform, mode }),
+    label,
+  }),
+  uninstallStackService,
+} = {}) {
+  if (typeof uninstallStackService !== 'function') {
+    throw new Error('[stack] archive service cleanup requires the canonical service uninstall owner');
+  }
+
+  const removedModes = [];
+  for (const candidate of definitionCandidates) {
+    const hasDefinition = definitionExists(candidate.path);
+    // Missing files are not proof of absence because historical teardown swallowed OS failures.
+    // Definition files are also not proof of registration. Query every candidate read-only so the
+    // canonical uninstall owner can remove an absent job's stale definition without teardown mutation.
+    // eslint-disable-next-line no-await-in-loop
+    const registration = await inspectRegistration({ mode: candidate.mode, path: candidate.path });
+    if (!hasDefinition && registration !== 'registered') continue;
+    // eslint-disable-next-line no-await-in-loop
+    await uninstallStackService({
+      rootDir,
+      stackName,
+      svcCmd: 'uninstall',
+      args: [`--mode=${candidate.mode}`],
+    });
+    removedModes.push(candidate.mode);
+  }
+  return { removedModes };
+}

package/scripts/utils/service/archive_service_lifecycle.test.mjs

@@ -0,0 +1,88 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { createTempFixture } from '../../testkit/core/temp_fixture.mjs';
+import {
+  disableInstalledStackServicesBeforeArchive,
+  resolveStackServiceDefinitionCandidates,
+} from './archive_service_lifecycle.mjs';
+
+test('archive service lifecycle resolves platform service definitions for the stack label', () => {
+  assert.deepEqual(
+    resolveStackServiceDefinitionCandidates({ platform: 'darwin', homeDir: '/home/alice', label: 'dev.happier.stack.exp' }),
+    [{ mode: 'user', path: '/home/alice/Library/LaunchAgents/dev.happier.stack.exp.plist' }],
+  );
+  assert.deepEqual(
+    resolveStackServiceDefinitionCandidates({ platform: 'linux', homeDir: '/home/alice', label: 'dev.happier.stack.exp' }),
+    [
+      { mode: 'user', path: '/home/alice/.config/systemd/user/dev.happier.stack.exp.service' },
+      { mode: 'system', path: '/etc/systemd/system/dev.happier.stack.exp.service' },
+    ],
+  );
+  assert.deepEqual(
+    resolveStackServiceDefinitionCandidates({ platform: 'win32', homeDir: 'C:\\Users\\alice', label: 'dev.happier.stack.exp' }),
+    [
+      { mode: 'user', path: 'C:\\Users\\alice\\.happier\\services\\dev.happier.stack.exp.ps1' },
+      { mode: 'system', path: 'C:\\ProgramData\\happier\\services\\dev.happier.stack.exp.ps1' },
+    ],
+  );
+});
+
+test('archive service lifecycle uninstalls evidenced user service without mutating an absent privileged mode', async (t) => {
+  const fixture = await createTempFixture(t, { prefix: 'stack-archive-service-lifecycle-' });
+  const userDefinition = join(fixture.root, '.config', 'systemd', 'user', 'dev.happier.stack.exp.service');
+  await mkdir(join(fixture.root, '.config', 'systemd', 'user'), { recursive: true });
+  await writeFile(userDefinition, 'service', 'utf8');
+  const calls = [];
+
+  const result = await disableInstalledStackServicesBeforeArchive({
+    rootDir: '/repo/apps/stack',
+    stackName: 'exp',
+    platform: 'linux',
+    homeDir: fixture.root,
+    definitionCandidates: [
+      { mode: 'user', path: userDefinition },
+      { mode: 'system', path: join(fixture.root, 'missing-system.service') },
+    ],
+    inspectRegistration: async ({ mode }) => mode === 'system' ? 'absent' : 'registered',
+    uninstallStackService: async (params) => calls.push(params),
+  });
+
+  assert.deepEqual(calls, [{ rootDir: '/repo/apps/stack', stackName: 'exp', svcCmd: 'uninstall', args: ['--mode=user'] }]);
+  assert.deepEqual(result, { removedModes: ['user'] });
+});
+
+test('archive service lifecycle removes a registered orphan even when its definition is already missing', async () => {
+  const calls = [];
+  const result = await disableInstalledStackServicesBeforeArchive({
+    rootDir: '/repo/apps/stack',
+    stackName: 'exp',
+    platform: 'darwin',
+    homeDir: '/home/alice',
+    definitionCandidates: [{ mode: 'user', path: '/missing/dev.happier.stack.exp.plist' }],
+    definitionExists: () => false,
+    inspectRegistration: async () => 'registered',
+    uninstallStackService: async (params) => calls.push(params),
+  });
+
+  assert.deepEqual(calls, [{ rootDir: '/repo/apps/stack', stackName: 'exp', svcCmd: 'uninstall', args: ['--mode=user'] }]);
+  assert.deepEqual(result, { removedModes: ['user'] });
+});
+
+test('archive service lifecycle delegates stale definition removal when registration is proven absent', async () => {
+  const calls = [];
+  await disableInstalledStackServicesBeforeArchive({
+    rootDir: '/repo/apps/stack',
+    stackName: 'exp',
+    platform: 'darwin',
+    homeDir: '/home/alice',
+    definitionCandidates: [{ mode: 'user', path: '/existing/dev.happier.stack.exp.plist' }],
+    definitionExists: () => true,
+    inspectRegistration: async () => 'absent',
+    uninstallStackService: async (params) => calls.push(params),
+  });
+
+  assert.deepEqual(calls, [{ rootDir: '/repo/apps/stack', stackName: 'exp', svcCmd: 'uninstall', args: ['--mode=user'] }]);
+});

package/scripts/utils/service/daemon_autostart.mjs

@@ -90,7 +90,7 @@ export function createServiceDaemonAutostarter({
   const tick = async () => {
     if (!running) return;
     if (isDown()) return stop();
-    if (daemonRunning()) return stop();
+    if (await daemonRunning()) return stop();
     if (inFlight) return;
 
     inFlight = true;

package/scripts/utils/service/daemon_autostart.test.mjs

@@ -184,6 +184,40 @@ test('createServiceDaemonAutostarter stops once daemon is running', async () =>
   assert.equal(scheduler.queued().length, 0);
 });
 
+test('createServiceDaemonAutostarter awaits async daemon-running checks before stopping', async () => {
+  const scheduler = createFakeScheduler();
+  const calls = { start: 0, daemonChecks: 0 };
+
+  const autostarter = createServiceDaemonAutostarter({
+    enabled: true,
+    isShuttingDown: () => false,
+    isServerReady: async () => true,
+    pollMs: 5000,
+    maxAttemptsPerCredentials: 2,
+    retryBaseMs: 1000,
+    retryMaxMs: 10_000,
+    nowMs: scheduler.now,
+    schedule: scheduler.schedule,
+    cancel: scheduler.cancel,
+    getCredentialFingerprint: async () => 'cred:a',
+    isDaemonRunning: async () => {
+      calls.daemonChecks += 1;
+      return false;
+    },
+    startDaemon: async () => {
+      calls.start += 1;
+    },
+    logger: { log: () => {}, warn: () => {}, error: () => {} },
+  });
+
+  autostarter.start();
+  await scheduler.advanceOne();
+
+  assert.equal(calls.daemonChecks, 1);
+  assert.equal(calls.start, 1);
+  assert.equal(scheduler.queued().length, 0);
+});
+
 test('createServiceDaemonAutostarter waits for server readiness before starting daemon', async () => {
   const scheduler = createFakeScheduler();
   const calls = { start: 0 };

package/scripts/utils/service/service_manager.mjs

@@ -3,6 +3,7 @@ import { rm } from 'node:fs/promises';
 import {
   resolveServiceBackend,
   buildServiceDefinition,
+  inspectServiceRegistration,
   planServiceAction,
   applyServicePlan,
 } from '@happier-dev/cli-common/service';
@@ -61,6 +62,12 @@ export async function uninstallService({
   const backend = resolveServiceBackend({ platform, mode });
   const definition = buildServiceDefinition({ backend, homeDir, spec });
   const taskName = taskNameFor({ backend, label });
+  const registration = inspectServiceRegistration({ backend, label, taskName, uid });
+
+  if (registration === 'absent') {
+    await rm(definition.path, { force: true });
+    return { backend, taskName: taskName || null };
+  }
 
   const plan = planServiceAction({
     backend,
@@ -73,7 +80,7 @@ export async function uninstallService({
     uid,
   });
   await applyServicePlan(plan);
-  await rm(definition.path, { force: true }).catch(() => {});
+  await rm(definition.path, { force: true });
   return { backend, taskName: taskName || null };
 }
 
@@ -94,3 +101,21 @@ export async function restartService({ platform = process.platform, mode = 'user
   return { backend };
 }
 
+export async function stopService({ platform = process.platform, mode = 'user', homeDir = '', spec, persistent = true, uid = null } = {}) {
+  const label = normalizeLabel(spec);
+  const backend = resolveServiceBackend({ platform, mode });
+  const definition = buildServiceDefinition({ backend, homeDir, spec });
+  const taskName = taskNameFor({ backend, label });
+
+  const plan = planServiceAction({
+    backend,
+    action: 'stop',
+    label,
+    definitionPath: definition.path,
+    taskName,
+    persistent,
+    uid,
+  });
+  await applyServicePlan(plan);
+  return { backend };
+}

package/scripts/utils/service/service_manager.plan.test.mjs

@@ -1,7 +1,10 @@
 import assert from 'node:assert/strict';
+import { access, mkdtemp, readFile, rm, writeFile, chmod, mkdir } from 'node:fs/promises';
 import test from 'node:test';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
 
-import { planServiceAction } from './service_manager.mjs';
+import { buildServiceDefinition, planServiceAction, stopService, uninstallService } from './service_manager.mjs';
 
 test('planServiceAction plans a systemd user install', () => {
   const plan = planServiceAction({
@@ -35,3 +38,186 @@ test('planServiceAction plans a windows task install', () => {
   assert.ok(plan.commands.some((c) => c.cmd === 'schtasks' && c.args.includes('/Run')));
 });
 
+test('stopService passes the launchd definition path for persistent macOS services', async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'happier-service-stop-launchd-'));
+  const binDir = join(tempRoot, 'bin');
+  const logPath = join(tempRoot, 'launchctl.log');
+  const previousPath = process.env.PATH;
+  const previousLogPath = process.env.HAPPIER_TEST_LAUNCHCTL_LOG_PATH;
+
+  t.after(async () => {
+    process.env.PATH = previousPath;
+    if (previousLogPath == null) {
+      delete process.env.HAPPIER_TEST_LAUNCHCTL_LOG_PATH;
+    } else {
+      process.env.HAPPIER_TEST_LAUNCHCTL_LOG_PATH = previousLogPath;
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await mkdir(binDir, { recursive: true });
+  const launchctlPath = join(binDir, 'launchctl');
+  await writeFile(
+    launchctlPath,
+    [
+      '#!/usr/bin/env node',
+      "const fs = require('node:fs');",
+      "const logPath = process.env.HAPPIER_TEST_LAUNCHCTL_LOG_PATH;",
+      "if (logPath) fs.appendFileSync(logPath, `${JSON.stringify(process.argv.slice(2))}\\n`, 'utf8');",
+    ].join('\n'),
+    'utf8',
+  );
+  await chmod(launchctlPath, 0o755);
+
+  process.env.PATH = `${binDir}${process.platform === 'win32' ? ';' : ':'}${previousPath ?? ''}`;
+  process.env.HAPPIER_TEST_LAUNCHCTL_LOG_PATH = logPath;
+
+  await assert.doesNotReject(
+    stopService({
+      platform: 'darwin',
+      mode: 'user',
+      homeDir: tempRoot,
+      spec: {
+        label: 'dev.happier.selfhost',
+        description: 'Happier test service',
+        programArgs: ['/tmp/happier-server'],
+        workingDirectory: tempRoot,
+      },
+      persistent: true,
+      uid: 501,
+    }),
+  );
+
+  const launchctlInvocations = (await readFile(logPath, 'utf8'))
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  const bootoutInvocation = launchctlInvocations.find((args) => args[0] === 'bootout');
+
+  assert.deepEqual(bootoutInvocation, [
+    'bootout',
+    'gui/501',
+    join(tempRoot, 'Library', 'LaunchAgents', 'dev.happier.selfhost.plist'),
+  ]);
+});
+
+test('uninstallService removes definitions only after backend-confirmed teardown', async (t) => {
+  for (const { platform, command, mode, uid } of [
+    { platform: 'linux', command: 'systemctl', mode: 'user', uid: 501 },
+    { platform: 'darwin', command: 'launchctl', mode: 'user', uid: 501 },
+    { platform: 'win32', command: 'powershell.exe', mode: 'user', uid: null },
+  ]) {
+    for (const outcome of ['absent', 'denied']) {
+      // eslint-disable-next-line no-await-in-loop
+      await t.test(`${command} ${outcome}`, async () => {
+        const tempRoot = await mkdtemp(join(tmpdir(), `happier-service-uninstall-${command}-`));
+        const binDir = join(tempRoot, 'bin');
+        const logPath = join(tempRoot, 'service-command.log');
+        const previousPath = process.env.PATH;
+        const previousLogPath = process.env.HAPPIER_TEST_SERVICE_LOG;
+        try {
+          await mkdir(binDir, { recursive: true });
+          const commandPath = join(binDir, command);
+          const behavior = outcome === 'denied'
+            ? '#!/bin/sh\necho "Access is denied: Permission denied" >&2\nexit 1\n'
+            : command === 'systemctl'
+              ? '#!/bin/sh\ncase "$*" in *daemon-reload*) exit 0;; esac\necho "Unit dev.happier.stack.test.service does not exist." >&2\nexit 1\n'
+              : command === 'launchctl'
+                ? '#!/bin/sh\necho "Could not find specified service" >&2\nexit 1\n'
+                : '#!/bin/sh\necho \'{"exists":false,"state":null,"lastTaskResult":null}\'\nexit 0\n';
+          const script = behavior.replace('#!/bin/sh\n', '#!/bin/sh\necho "$*" >> "$HAPPIER_TEST_SERVICE_LOG"\n');
+          await writeFile(commandPath, script, 'utf8');
+          await chmod(commandPath, 0o755);
+          process.env.PATH = `${binDir}:${previousPath ?? ''}`;
+          process.env.HAPPIER_TEST_SERVICE_LOG = logPath;
+
+          const spec = { label: 'dev.happier.stack.test', programArgs: ['/tmp/hstack', 'start', '--restart'] };
+          const backend = platform === 'linux' ? 'systemd-user' : platform === 'darwin' ? 'launchd-user' : 'schtasks-user';
+          const definition = buildServiceDefinition({ backend, homeDir: tempRoot, spec });
+          await mkdir(dirname(definition.path), { recursive: true });
+          await writeFile(definition.path, definition.contents, 'utf8');
+
+          const operation = uninstallService({ platform, mode, homeDir: tempRoot, spec, uid });
+          if (outcome === 'denied') {
+            await assert.rejects(operation, /denied|permission|command failed/i);
+            await access(definition.path);
+          } else {
+            await assert.doesNotReject(operation);
+            await assert.rejects(access(definition.path));
+            const invocations = await readFile(logPath, 'utf8');
+            if (command === 'systemctl') {
+              assert.match(invocations, /--user show dev\.happier\.stack\.test\.service/);
+              assert.doesNotMatch(invocations, /disable|daemon-reload/);
+            } else if (command === 'launchctl') {
+              assert.match(invocations, /print gui\/501\/dev\.happier\.stack\.test/);
+              assert.doesNotMatch(invocations, /bootout|disable|\.plist/);
+            } else {
+              assert.match(invocations, /Get-ScheduledTask/);
+              assert.doesNotMatch(invocations, /Stop-ScheduledTask|Unregister-ScheduledTask/);
+            }
+          }
+        } finally {
+          process.env.PATH = previousPath;
+          if (previousLogPath == null) delete process.env.HAPPIER_TEST_SERVICE_LOG;
+          else process.env.HAPPIER_TEST_SERVICE_LOG = previousLogPath;
+          await rm(tempRoot, { recursive: true, force: true });
+        }
+      });
+    }
+  }
+});
+
+test('uninstallService tears down a registered launchd orphan by label when its plist is missing', async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'happier-service-uninstall-launchd-orphan-'));
+  const binDir = join(tempRoot, 'bin');
+  const logPath = join(tempRoot, 'launchctl.log');
+  const previousPath = process.env.PATH;
+  const previousLogPath = process.env.HAPPIER_TEST_SERVICE_LOG;
+  t.after(async () => {
+    process.env.PATH = previousPath;
+    if (previousLogPath == null) delete process.env.HAPPIER_TEST_SERVICE_LOG;
+    else process.env.HAPPIER_TEST_SERVICE_LOG = previousLogPath;
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+  await mkdir(binDir, { recursive: true });
+  const launchctlPath = join(binDir, 'launchctl');
+  await writeFile(launchctlPath, '#!/bin/sh\necho "$*" >> "$HAPPIER_TEST_SERVICE_LOG"\nexit 0\n', 'utf8');
+  await chmod(launchctlPath, 0o755);
+  process.env.PATH = `${binDir}:${previousPath ?? ''}`;
+  process.env.HAPPIER_TEST_SERVICE_LOG = logPath;
+
+  const spec = { label: 'dev.happier.stack.orphan', programArgs: ['/tmp/hstack', 'start', '--restart'] };
+  await uninstallService({ platform: 'darwin', mode: 'user', homeDir: tempRoot, spec, uid: 501 });
+
+  const invocations = await readFile(logPath, 'utf8');
+  assert.match(invocations, /print gui\/501\/dev\.happier\.stack\.orphan/);
+  assert.match(invocations, /bootout gui\/501\/dev\.happier\.stack\.orphan/);
+  assert.match(invocations, /disable gui\/501\/dev\.happier\.stack\.orphan/);
+  assert.doesNotMatch(invocations, /\.plist/);
+});
+
+test('uninstallService propagates stale definition removal failure after proving registration absent', async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'happier-service-uninstall-rm-failure-'));
+  const binDir = join(tempRoot, 'bin');
+  const previousPath = process.env.PATH;
+  t.after(async () => {
+    process.env.PATH = previousPath;
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+  await mkdir(binDir, { recursive: true });
+  const systemctlPath = join(binDir, 'systemctl');
+  await writeFile(systemctlPath, '#!/bin/sh\necho "Unit dev.happier.stack.rm-failure.service could not be found." >&2\nexit 1\n', 'utf8');
+  await chmod(systemctlPath, 0o755);
+  process.env.PATH = `${binDir}:${previousPath ?? ''}`;
+
+  const spec = { label: 'dev.happier.stack.rm-failure', programArgs: ['/tmp/hstack', 'start', '--restart'] };
+  const definition = buildServiceDefinition({ backend: 'systemd-user', homeDir: tempRoot, spec });
+  await mkdir(definition.path, { recursive: true });
+
+  await assert.rejects(
+    uninstallService({ platform: 'linux', mode: 'user', homeDir: tempRoot, spec, uid: 501 }),
+    /directory|operation not permitted|is a directory|eisdir/i,
+  );
+  await access(definition.path);
+});