@agfpd/iapeer 0.4.7 → 0.4.9

package/src/shadow/index.ts

@@ -1,174 +0,0 @@
-// Read-only fidelity OBSERVER for the tmux→pty migration (prod burn-in track).
-//
-// For each warm claude/codex peer it builds an @xterm/headless model from the daemon's
-// EXISTING pipe-pane log (`<identity>.log` under cfg.logDir) — the same raw child bytes
-// tmux's emulator gets — and compares the PTY-model verdicts (composer-occupancy / ready-gate
-// / liveness) to the live AUTHORITATIVE tmux verdicts, logging divergences + rolling fidelity
-// to `<eventLogDir>/shadow-fidelity.{jsonl,json}`.
-//
-// STRICTLY READ-ONLY: it tails log FILES and runs read-only tmux (`capture-pane`/`display`/
-// `has-session`). It NEVER delivers, sends keys, spawns, or touches delivery/lifecycle/
-// registry/launch. Nothing in the delivery/lifecycle hot paths imports this module — it runs
-// ONLY via the `iapeer shadow` CLI verb (dynamic-imported, so @xterm is never loaded in the
-// daemon). With it off, the daemon's behavior is byte-identical. This is the prod burn-in:
-// the supervisor's model proven alongside tmux on real traffic BEFORE any delivery cutover.
-import { Terminal } from '@xterm/headless'
-import { openSync, closeSync, fstatSync, readSync, existsSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join } from 'node:path'
-import { tmux, composerCaptureHasHumanInput, listOnlinePeers } from '../transport/index.ts'
-import { getAdapter } from '../launch/index.ts'
-import { ptyHostEnabled } from '../launch/ptyHost.ts' // spawn-flip Ф0b-3: the observer skips supervisor-hosted peers
-import { buildSocketPath, buildProcessAddress } from '../core/socket.ts'
-import type { Runtime } from '../core/constants.ts'
-import { GateTracker, classifyDirection, evaluateReadyGateFlipEligibility, VERDICTS } from './gate.ts'
-// modelToPlainText lives in the leaf render.ts (shared with readyGateModel + the supervisor
-// boot-driver); re-exported here so existing importers of './index.ts' keep resolving.
-import { composerOccupancyFromModel, modelToPlainText } from './render.ts'
-export { composerOccupancyFromModel, modelToPlainText }
-
-const SEED_BYTES = 4 * 1024 * 1024
-const pidAlive = (pid: number): boolean => {
-  try { process.kill(pid, 0); return true } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM' }
-}
-
-interface Obs { addr: string; sock: string; runtime: Runtime; cols: number; rows: number; term: Terminal; fd: number; offset: number }
-
-export interface ShadowOptions {
-  logDir: string        // daemon pane-logs live here (<identity>.log)
-  eventLogDir: string   // shadow-fidelity.{jsonl,json} written here
-  sockDir: string
-  intervalMs?: number
-  maxMinutes?: number   // 0/undefined + once=false → run until <eventLogDir>/shadow-fidelity.STOP
-  once?: boolean
-  log?: (s: string) => void
-}
-
-/** Feed the pane-log delta into the model; resolves with the byte count appended this tick
- *  (drives the coverage state classifier: >0 ⇒ the model is advancing, not idle). */
-function feed(o: Obs): Promise<number> {
-  const sz = fstatSync(o.fd).size
-  if (sz <= o.offset) return Promise.resolve(0)
-  const buf = Buffer.alloc(sz - o.offset)
-  readSync(o.fd, buf, 0, buf.length, o.offset)
-  o.offset = sz
-  return new Promise(res => o.term.write(buf, () => res(buf.length)))
-}
-
-export function enumerate(models: Map<string, Obs>, opts: ShadowOptions, tracker?: GateTracker): void {
-  let peers: { runtime: Runtime; personality: string }[] = []
-  try { peers = listOnlinePeers(opts.sockDir).filter(p => p.runtime === 'claude' || p.runtime === 'codex') } catch { return }
-  const live = new Set<string>()
-  for (const p of peers) {
-    const addr = buildProcessAddress(p.runtime, p.personality)
-    // SPAWN-FLIP Ф0b-3: NEVER measure a supervisor-HOSTED peer. The observer's premise is pty-model vs
-    // LIVE TMUX, so it only compares peers that are actually on tmux. pty-hosting is now the DEFAULT, so
-    // ptyHostEnabled is true for a normal peer (hosted → skip) and false only for an explicit `.no-pty-host`
-    // opt-OUT peer (tmux → compared). Skip BEFORE `live` — a peer that flips falls out of `live` and is
-    // reaped. (Post-migration the whole fleet is pty-default, so this skips everything and the observer is
-    // effectively retired until/unless a peer opts back to tmux.)
-    if (ptyHostEnabled(opts.logDir, addr)) continue
-    live.add(addr)
-    if (models.has(addr)) continue
-    try {
-      const sock = buildSocketPath(p.runtime, p.personality, opts.sockDir)
-      const log = join(opts.logDir, `${addr}.log`); if (!existsSync(log)) continue
-      const geo = tmux(sock, 'display', '-p', '-t', addr, '#{pane_width}x#{pane_height}'); if (!geo.ok) continue
-      const [cols, rows] = geo.out.trim().split('x').map(Number); if (!cols || !rows) continue
-      const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 3000 })
-      const fd = openSync(log, 'r'); const offset = Math.max(0, fstatSync(fd).size - SEED_BYTES)
-      models.set(addr, { addr, sock, runtime: p.runtime, cols, rows, term, fd, offset })
-    } catch { /* a peer racing spawn/teardown — skip this round */ }
-  }
-  for (const [addr, o] of models) if (!live.has(addr)) { try { closeSync(o.fd) } catch { /* */ }; tracker?.peerGone(addr); models.delete(addr) }
-}
-
-/** Run the read-only fidelity observer. Resolves when once/maxMinutes/STOP completes. */
-export async function runShadowFidelity(opts: ShadowOptions): Promise<void> {
-  mkdirSync(opts.eventLogDir, { recursive: true })
-  const jsonl = join(opts.eventLogDir, 'shadow-fidelity.jsonl')
-  const statsFile = join(opts.eventLogDir, 'shadow-fidelity.json')
-  const stopFile = join(opts.eventLogDir, 'shadow-fidelity.STOP')
-  const interval = opts.intervalMs ?? 5000
-  const log = opts.log ?? (() => { /* */ })
-  const models = new Map<string, Obs>()
-  const tracker = new GateTracker()
-  const startedISO = new Date().toISOString(), t0 = Date.now()
-  enumerate(models, opts, tracker)
-  for (const o of models.values()) await feed(o)  // seed each model
-  log(`shadow-fidelity: ${models.size} warm peers, interval ${interval}ms\n`)
-  let i = 0
-  for (;;) {
-    if (opts.maxMinutes && Date.now() - t0 >= opts.maxMinutes * 60000) break
-    if (existsSync(stopFile)) break
-    // Re-enroll every ~3 ticks (~15s), not 15 (~75s): a freshly-woken peer must be enrolled
-    // and sampled DURING its not-ready phase for a readiness transition (the center cell) to
-    // register — a 75s enroll-lag could first-sight it already-ready and miss the transition.
-    if (i > 0 && i % 3 === 0) enumerate(models, opts, tracker)
-    tracker.tickStart(models.size)
-    for (const o of models.values()) {
-      try {
-        const bytesFed = await feed(o)
-        const adapter = getAdapter(o.runtime)
-        const capE = tmux(o.sock, 'capture-pane', '-e', '-p', '-t', o.addr); if (!capE.ok) continue
-        const occTmux = composerCaptureHasHumanInput(capE.out, adapter.deliveryMarkers)
-        const occPty = composerOccupancyFromModel(o.term, o.cols, o.rows, o.runtime)
-        const capP = tmux(o.sock, 'capture-pane', '-p', '-t', o.addr)
-        const rgTmux = capP.ok ? adapter.isInputReady(capP.out) : null
-        const rgPty = adapter.isInputReady(modelToPlainText(o.term, o.cols, o.rows))
-        const livTmux = tmux(o.sock, 'has-session', '-t', o.addr).ok
-        const ppid = tmux(o.sock, 'display', '-p', '-t', o.addr, '#{pane_pid}')
-        const pid = ppid.ok ? Number(ppid.out.trim()) : NaN
-        const livPty = Number.isFinite(pid) ? pidAlive(pid) : false
-        const hasHistory = o.term.buffer.active.baseY > 0
-
-        // Feed the gate tracker — it scores DIRECTION (behind=hard / ahead=benign-if-boot-self-heal)
-        // and accumulates the COVERAGE matrix. The boolean booleans never leave this call.
-        tracker.sample(i, {
-          peer: o.addr, runtime: o.runtime,
-          occupancy: { pty: occPty, tmux: occTmux },
-          readyGate: { pty: rgPty, tmux: rgTmux },
-          liveness: { pty: livPty, tmux: livTmux },
-          bytesFed, hasHistory,
-        })
-
-        // DIRECTION-AWARE per-event divergence trail (gate scoring lives in the tracker; this is
-        // the forensic log). Occupancy carries the raw capture + model frames for root-cause.
-        const occDir = classifyDirection(occPty, occTmux)
-        const rgDir = rgTmux === null ? 'agree' : classifyDirection(rgPty, rgTmux)
-        const livDir = classifyDirection(livPty, livTmux)
-        if (occDir !== 'agree' || rgDir !== 'agree' || livDir !== 'agree') {
-          appendFileSync(jsonl, JSON.stringify({
-            ts: new Date().toISOString(), peer: o.addr, geom: `${o.cols}x${o.rows}`, hasHistory,
-            occupancy: { pty: occPty, tmux: occTmux, dir: occDir },
-            readyGate: { pty: rgPty, tmux: rgTmux, dir: rgDir },
-            liveness: { pty: livPty, tmux: livTmux, dir: livDir },
-            ...(occDir !== 'agree' ? { capE: capE.out.slice(-2500), model: modelToPlainText(o.term, o.cols, o.rows).slice(-2500) } : {}),
-          }) + '\n')
-          log(`DIVERGE ${o.addr} occ=${occDir} rg=${rgDir} liv=${livDir}\n`)
-        }
-      } catch { /* an observer error must NEVER escape — it is a passive sidecar */ }
-    }
-    i++
-    const gs = tracker.summary()
-    const totalSamples = VERDICTS.reduce((n, v) => n + gs.verdicts[v].samples, 0)
-    writeFileSync(statsFile, JSON.stringify({
-      startedISO, lastISO: new Date().toISOString(), elapsedMin: +((Date.now() - t0) / 60000).toFixed(1),
-      peers: models.size, samples: totalSamples,
-      // Gate criterion: clean iff zero hard divergences across all verdicts. Hard =
-      // every pty-behind + non-benign pty-ahead (steady-state or non-converging). Benign =
-      // boot-window ahead that self-heals within budget. Coverage proves the matrix was traversed.
-      gateClean: VERDICTS.every(v => gs.verdicts[v].gateClean),
-      hardTotal: gs.hardViolations.length,
-      // Ready-gate FLIP eligibility (first-flip verdict) self-reported: NECESSARY input, not an
-      // auto-trigger — the flip stays an explicit decision. On !eligible, `reasons` say which cell
-      // is empty/dirty (actionable). composer-busy is excluded (orthogonal — gates the later occupancy flip).
-      readyGateFlip: evaluateReadyGateFlipEligibility(gs),
-      verdicts: gs.verdicts,
-      coverage: gs.coverage,
-      recentHard: gs.hardViolations.slice(-20),
-    }, null, 2))
-    if (opts.once) break
-    await new Promise(r => setTimeout(r, interval))
-  }
-  for (const o of models.values()) { try { closeSync(o.fd) } catch { /* */ } }
-}

package/src/shadow/install.ts

@@ -1,256 +0,0 @@
-// Code-managed install / teardown / update-recycle for the read-only tmux→pty fidelity
-// BURN-IN job (`iapeer shadow`). The OBSERVER itself is src/shadow/index.ts (it loads
-// @xterm/headless); THIS module is PURE launchd plumbing — it imports NO @xterm — so the
-// deploy path (update/rollback) and the CLI can install/recycle the job without pulling the
-// terminal emulator into their import graph (the daemon hot path stays @xterm-free).
-//
-// The job is a foundation-OWNED, always-on launchd LaunchAgent (com.iapeer.shadow-fidelity)
-// running the INSTALLED binary `iapeer shadow`. It is NOT a registry peer — it receives no
-// IAP and has no peer profile — so recycleFoundationOwnedInfraJobs' registry SCAN cannot see
-// it; cycleShadowJob recycles it by LABEL instead. It carries the same ownership sentinel as
-// every foundation plist, so the collision guard (install) and the recycle guard both
-// recognize it as ours. KeepAlive owns its lifecycle; stop it with `iapeer shadow-uninstall`
-// (bootout + rm), NEVER the STOP sentinel file (KeepAlive would just respawn straight past it).
-
-import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { IAPEER_DIR } from '../core/constants.ts'
-import { IapError } from '../core/errors.ts'
-import { iapeerBinPath } from '../install/index.ts'
-import { pluginLogsDir } from '../storage/index.ts'
-import {
-  cycleLaunchdJob,
-  isFoundationOwnedPlist,
-  launchAgentsDir,
-  launchctlBootstrap,
-  launchdLabel,
-  renderLaunchdPlist,
-  type LaunchdJobCycleResult,
-  type LaunchdPlistSpec,
-} from '../launch/launchd.ts'
-
-/** The burn-in job's personality stem → label com.iapeer.shadow-fidelity (the running job). */
-export const SHADOW_PERSONALITY = 'shadow-fidelity'
-/** com.iapeer.shadow-fidelity — keyed through launchdLabel so the scheme has ONE source. */
-export const SHADOW_PLIST_LABEL = launchdLabel(SHADOW_PERSONALITY)
-
-export function shadowPlistPath(env: NodeJS.ProcessEnv = process.env): string {
-  return join(launchAgentsDir(env), `${SHADOW_PLIST_LABEL}.plist`)
-}
-
-/** The STOP sentinel the observer polls (under <eventLogDir>=~/.iapeer/logs/iapeer). Under
- *  KeepAlive a STALE one would respawn the observer straight into an immediate exit → a
- *  throttle-storm, so installShadowJob clears it before (re)loading. */
-function shadowStopFile(env: NodeJS.ProcessEnv = process.env): string {
-  return join(pluginLogsDir('iapeer', { env }), 'shadow-fidelity.STOP')
-}
-
-function inSandbox(env: NodeJS.ProcessEnv): boolean {
-  return env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1'
-}
-
-/** Resolve the gui-domain uid, or null when `id -u` is non-numeric (never assume 0). */
-function uidOrNull(): string | null {
-  const u = (spawnSync('id', ['-u'], { encoding: 'utf8' }).stdout ?? '').trim()
-  return /^\d+$/.test(u) ? u : null
-}
-
-/** Is com.iapeer.shadow-fidelity currently loaded in the gui domain? */
-function isShadowLoaded(): boolean {
-  const uid = uidOrNull()
-  if (!uid) return false
-  return spawnSync('launchctl', ['print', `gui/${uid}/${SHADOW_PLIST_LABEL}`], { stdio: 'ignore' }).status === 0
-}
-
-/**
- * Build the burn-in job's launchd plist spec (PURE — render/lint-testable). Runs the
- * INSTALLED `iapeer shadow` (prod decoupled from the src tree). The launchd-minimal PATH
- * MUST include /opt/homebrew/bin: the observer shells READ-ONLY tmux (capture-pane /
- * has-session / display), and tmux lives there — a bare PATH would make every tmux probe
- * fail (no peers enumerated). Deterministic (curated PATH, not env.PATH) so the rendered
- * plist is byte-stable across deploys → installShadowPlist's write-if-changed stays a no-op
- * when nothing actually changed (no Background Task Management notification spam).
- */
-export function buildShadowPlistSpec(env: NodeJS.ProcessEnv = process.env): LaunchdPlistSpec {
-  const home = env.HOME?.trim() || homedir()
-  const defaultPath = `${home}/.local/bin:${home}/.bun/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`
-  const logDir = pluginLogsDir('iapeer', { env })
-  const environment: Record<string, string> = { PATH: env.IAPEER_SHADOW_PATH?.trim() || defaultPath }
-  // Sandbox/test parity (mirror of installDaemonPlist / installAlwaysOnPlist): bake the
-  // non-default root overrides so a SANDBOXED install resolves the SAME isolated tree the
-  // observer reads. In production these are unset → nothing baked, real ~/.iapeer + /tmp used.
-  for (const key of ['IAPEER_ROOT', 'IAPEER_SOCK_DIR', 'IAPEER_LAUNCHAGENTS_DIR'] as const) {
-    if (env[key]?.trim()) environment[key] = env[key]!.trim()
-  }
-  return {
-    label: SHADOW_PLIST_LABEL,
-    programArguments: [iapeerBinPath(env), 'shadow'],
-    workingDirectory: home, // cwd-agnostic (the observer resolves paths from IAPEER_ROOT/cfg)
-    environment,
-    stdoutPath: join(logDir, 'shadow-fidelity.launchd-stdout.log'),
-    stderrPath: join(logDir, 'shadow-fidelity.launchd-stderr.log'),
-  }
-}
-
-export interface InstallShadowPlistResult {
-  path: string
-  /** false when the on-disk plist already matched byte-for-byte → NO write (no BTM spam). */
-  changed: boolean
-}
-
-/**
- * Write the burn-in plist (file only — does NOT load it). IDEMPOTENT BY CONTENT
- * (write-if-changed, mirror of installDaemonPlist: a byte-identical rewrite trips the owner's
- * Background Task Management notification for zero benefit). Collision guard: refuses to
- * overwrite a com.iapeer.shadow-fidelity.plist that lacks the ownership sentinel (a foreign
- * manager owns it) — the guard fires FIRST, before any mkdir/write, so a refusal leaves the
- * filesystem untouched.
- */
-export function installShadowPlist(env: NodeJS.ProcessEnv = process.env): InstallShadowPlistResult {
-  const path = shadowPlistPath(env)
-  if (existsSync(path) && !isFoundationOwnedPlist(path)) {
-    throw new IapError(
-      `refusing to overwrite ${path}: ${SHADOW_PLIST_LABEL} exists but is not foundation-managed ` +
-        `(no ownership sentinel) — another manager owns it`,
-    )
-  }
-  const rendered = renderLaunchdPlist(buildShadowPlistSpec(env))
-  mkdirSync(launchAgentsDir(env), { recursive: true })
-  // Never mkdir the REAL ~/.iapeer log dir under a sandbox that forgot IAPEER_ROOT (mirror
-  // installAlwaysOnPlist's guard); a real run (no sandbox flag) always makes it.
-  const logDir = pluginLogsDir('iapeer', { env })
-  const realRoot = join(homedir(), IAPEER_DIR)
-  if (!(inSandbox(env) && logDir.startsWith(`${realRoot}/`))) {
-    mkdirSync(logDir, { recursive: true, mode: 0o700 })
-  }
-  let existing: string | null = null
-  try {
-    existing = readFileSync(path, 'utf8')
-  } catch {
-    existing = null
-  }
-  if (existing === rendered) return { path, changed: false }
-  writeFileSync(path, rendered, { mode: 0o644 })
-  return { path, changed: true }
-}
-
-export type ShadowJobAction =
-  | 'loaded' // bootstrapped now (was not loaded)
-  | 'reloaded' // plist changed on an already-loaded job → bootout+bootstrap applied the new one
-  | 'already-loaded' // loaded and the plist did not change → left running untouched
-  | 'refused-foreign' // a non-foundation plist sits at the label → never loaded
-  | 'failed' // launchctl bootstrap/cycle failed (detail carries the rescue recipe)
-  | 'skipped-sandbox' // IAPEER_TEST_SANDBOX=1 → never touch real launchd
-
-export interface InstallShadowJobResult extends InstallShadowPlistResult {
-  action: ShadowJobAction
-  detail?: string
-}
-
-/**
- * Install the burn-in plist AND ensure the job is live: write-if-changed, clear a stale STOP
- * sentinel, then load it (or RELOAD via bootout+bootstrap when the plist content changed on
- * an already-loaded job — bootstrap alone is idempotent and would NOT pick up a changed
- * plist). Idempotent: a repeat call on an unchanged, loaded job is a no-op ('already-loaded').
- * Sandbox-safe: under IAPEER_TEST_SANDBOX it writes the (overridden-dir) plist FILE but never
- * calls launchctl ('skipped-sandbox'). This is the code-managed replacement for a hand-written
- * burn-in plist — reproducible, ownership-sentinel-guarded, fleet-deployable.
- */
-export function installShadowJob(env: NodeJS.ProcessEnv = process.env): InstallShadowJobResult {
-  const { path, changed } = installShadowPlist(env)
-  if (inSandbox(env)) return { path, changed, action: 'skipped-sandbox' }
-  // Clear a STALE STOP sentinel BEFORE (re)loading — else KeepAlive respawns the observer
-  // into an instant exit (it polls the STOP file) → 10s-throttled respawn storm.
-  try {
-    unlinkSync(shadowStopFile(env))
-  } catch {
-    /* none present */
-  }
-  if (isShadowLoaded()) {
-    if (!changed) return { path, changed, action: 'already-loaded' }
-    const c = cycleLaunchdJob(SHADOW_PLIST_LABEL, path, env)
-    return c.state === 'restarted'
-      ? { path, changed, action: 'reloaded' }
-      : { path, changed, action: 'failed', detail: c.detail }
-  }
-  const b = launchctlBootstrap(SHADOW_PERSONALITY, path, env)
-  const action: ShadowJobAction =
-    b.state === 'loaded'
-      ? 'loaded'
-      : b.state === 'already-loaded'
-        ? 'already-loaded'
-        : b.state === 'refused-foreign'
-          ? 'refused-foreign'
-          : b.state === 'skipped-sandbox'
-            ? 'skipped-sandbox'
-            : 'failed'
-  return { path, changed, action, detail: b.detail }
-}
-
-/**
- * Recycle the burn-in job by LABEL after a binary swap (deploy path). The plist runs the
- * just-replaced `iapeer shadow` off the same binary, so the SAME LWCR managed-launch-constraint
- * bomb that bit the daemon (EX_CONFIG(78) on a KeepAlive respawn into the stale constraint)
- * applies here too — only a full bootout→bootstrap clears it. It is NOT a registry peer, so
- * recycleFoundationOwnedInfraJobs' registry scan misses it; this cycles it directly. Only
- * touches a LOADED, foundation-owned job: absent / foreign / not-loaded → null (no-op).
- * Sandbox-safe (cycleLaunchdJob returns skipped-sandbox under the test flag).
- */
-export function cycleShadowJob(env: NodeJS.ProcessEnv = process.env): LaunchdJobCycleResult | null {
-  const path = shadowPlistPath(env)
-  if (!existsSync(path) || !isFoundationOwnedPlist(path)) return null
-  return cycleLaunchdJob(SHADOW_PLIST_LABEL, path, env)
-}
-
-export type ShadowUninstallAction =
-  | 'booted-out' // job was loaded → booted out, plist removed
-  | 'removed-not-loaded' // plist removed, job was not loaded
-  | 'absent' // nothing to do (no plist)
-  | 'refused-foreign' // the plist is not foundation-owned → left untouched
-  | 'skipped-sandbox'
-  | 'failed'
-
-export interface UninstallShadowJobResult {
-  path: string
-  action: ShadowUninstallAction
-  detail?: string
-}
-
-/**
- * Stop and remove the burn-in job — the CORRECT way to halt it (the STOP sentinel would be
- * respawned past by KeepAlive): bootout the loaded job, then delete the plist. Refuses a
- * non-foundation plist (ownership guard). Sandbox-safe. Reversibility for the install verb.
- */
-export function uninstallShadowJob(env: NodeJS.ProcessEnv = process.env): UninstallShadowJobResult {
-  const path = shadowPlistPath(env)
-  if (!existsSync(path)) return { path, action: 'absent' }
-  if (!isFoundationOwnedPlist(path)) {
-    return { path, action: 'refused-foreign', detail: `${path} is not foundation-owned — not booting it out` }
-  }
-  if (inSandbox(env)) return { path, action: 'skipped-sandbox' }
-  let action: ShadowUninstallAction = 'removed-not-loaded'
-  if (isShadowLoaded()) {
-    const uid = uidOrNull()
-    const r = uid
-      ? spawnSync('launchctl', ['bootout', `gui/${uid}/${SHADOW_PLIST_LABEL}`], { encoding: 'utf8' })
-      : { status: 1, stderr: 'cannot resolve uid' }
-    if (r.status !== 0 && isShadowLoaded()) {
-      return { path, action: 'failed', detail: `launchctl bootout failed: ${(r.stderr ?? '').trim() || `exit ${r.status}`}` }
-    }
-    action = 'booted-out'
-  }
-  // Also clear any STOP sentinel so a later reinstall starts clean.
-  try {
-    unlinkSync(shadowStopFile(env))
-  } catch {
-    /* none */
-  }
-  try {
-    rmSync(path)
-  } catch {
-    /* best-effort */
-  }
-  return { path, action }
-}