@agfpd/iapeer 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -943,6 +943,7 @@ const USAGE = `usage: iapeer <verb> [args]
   install                                                        build binary + global scaffold + daemon plist (one bootstrap)
   update [version] [--force]                                     pull latest (or exact) @agfpd/iapeer from npm + restart daemon + recycle owned infra jobs
   rollback                                                       revert to the previous binary (.prev) + restart daemon + recycle owned infra jobs
+  uninstall [--dry-run] [--yes] [--remove-codesign-identity]     remove THIS foundation install (binary, ~/.iapeer, daemon plist, PATH lines); refuses if a persistent-peer fleet is present
   version | --version | -v                                       print the installed binary's version
   help | --help | -h                                             print this usage (works appended to any verb; executes nothing)
   daemon [--install-plist]                                       run the host-wide HTTP-MCP router (launchd-held)
@@ -1639,6 +1640,53 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         ;(failed ? errOut : out)(msg)
         return failed ? 1 : 0
       }
+      case 'uninstall': {
+        // Symmetric foundation removal (namespace-safe; REFUSES on a foreign fleet).
+        // DESTRUCTIVE — removes ~/.iapeer (all peers/memory/logs). --dry-run previews;
+        // --yes skips the confirm; --remove-codesign-identity also drops the shared
+        // agfpd signing identity (otherwise kept).
+        const { planUninstall, executeUninstall } = await import('../uninstall/index.ts')
+        const removeCodesign = flags['remove-codesign-identity'] === true
+        const plan = planUninstall({ env, removeCodesignIdentity: removeCodesign })
+        if (plan.refused) {
+          errOut(`uninstall refused — ${plan.refused.reason}\n`)
+          return 1
+        }
+        out('iapeer uninstall — will remove:\n')
+        for (const it of plan.items) {
+          const mark = it.present ? '•' : '·'
+          const tail = it.detail ? ` — ${it.detail}` : it.present ? '' : ' — already gone'
+          out(`  ${mark} ${it.what}${it.path ? `  (${it.path})` : ''}${tail}\n`)
+        }
+        if (flags['dry-run'] === true) {
+          out('\n(dry-run — nothing removed)\n')
+          return 0
+        }
+        if (flags.yes !== true) {
+          if (process.stdin.isTTY !== true) {
+            errOut('\nuninstall is destructive (removes ~/.iapeer) — re-run with --yes in a non-interactive shell.\n')
+            return 2
+          }
+          const { createInterface } = await import('node:readline/promises')
+          const rl = createInterface({ input: process.stdin, output: process.stdout })
+          let answer = ''
+          try {
+            answer = (await rl.question('\nThis permanently removes iapeer and ALL its data. Continue? [y/N] ')).trim().toLowerCase()
+          } finally {
+            rl.close()
+          }
+          if (answer !== 'y' && answer !== 'yes') {
+            out('uninstall aborted.\n')
+            return 1
+          }
+        }
+        const res = executeUninstall({ env, removeCodesignIdentity: removeCodesign })
+        for (const r of res.removed) out(`  removed: ${r}\n`)
+        for (const s of res.skipped) out(`  skipped (absent): ${s}\n`)
+        for (const f of res.failed) errOut(`  FAILED: ${f.what} — ${f.detail}\n`)
+        out(res.failed.length ? '\nuninstall finished with errors (see above).\n' : '\niapeer uninstalled. (bun left in place.)\n')
+        return res.failed.length ? 1 : 0
+      }
       case 'install': {
         // UNIFIED foundation install (contract Установка §1 — "один npx ставит
         // фундамент"): ONE command does all three install-phase steps that used to be

package/src/index.ts

@@ -23,6 +23,8 @@ export * from './init/index.ts'
 export * from './install/index.ts'
 // Update — the cloud-only deploy path (`iapeer update`: npm latest → rebuild → restart).
 export * from './update/index.ts'
+// Uninstall — symmetric foundation removal (namespace-safe; refuses on a foreign fleet).
+export * from './uninstall/index.ts'
 // Onboard — the host-phase (idempotent marketplace registration in claude + codex).
 export * from './onboard/index.ts'
 // Memory slot — the declarative provider slot (контракт «Слот памяти»): status read + onboard step.

package/src/onboard/memory.ts

@@ -25,11 +25,26 @@ export interface MemoryOnboardOptions {
   skip?: boolean
   /** --memory <pkg>: override the provider package (default @agfpd/iapeer-memory). */
   package?: string
+  /** Host agentic runtime to thread to the provider init (`--runtime <rt>`) — the
+   *  onboard↔init contract: the provider provisions its role-peers (index/watcher/
+   *  timer) on THIS runtime instead of guessing. Omitted on a no-runtime host →
+   *  the provider degrades (base+BM25, role-peers skipped). */
+  runtime?: string
   dryRun?: boolean
   env?: NodeJS.ProcessEnv
+  /** Wall-clock backstop (ms) for the provider-init subprocess — a hung provider
+   *  (e.g. a stalled native build) must NEVER wedge onboard (memory is optional).
+   *  The interactive wizard passes a generous value; the linear path leaves it
+   *  unset (no timeout). */
+  timeoutMs?: number
   /** Injectable runner (tests). Default: availability probe + `npx -y <pkg> init …`
    *  with inherited stdio. */
-  runInit?: (pkg: string, args: string[], env: NodeJS.ProcessEnv) => { status: number | null; unavailable: boolean }
+  runInit?: (
+    pkg: string,
+    args: string[],
+    env: NodeJS.ProcessEnv,
+    timeoutMs?: number,
+  ) => { status: number | null; unavailable: boolean }
 }
 
 export interface MemoryOnboardResult {
@@ -49,17 +64,24 @@ function defaultRunInit(
   pkg: string,
   args: string[],
   env: NodeJS.ProcessEnv,
+  timeoutMs?: number,
 ): { status: number | null; unavailable: boolean } {
   // Availability probe FIRST (cheap, side-effect-free): an unpublished package /
   // no network → soft-skip per the contract (the provider's release order must
-  // never block the core's onboard).
-  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env })
+  // never block the core's onboard). Bounded so the probe itself cannot hang.
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env, timeout: 60_000 })
   if (probe.status !== 0) return { status: probe.status, unavailable: true }
   // INHERITED stdio — the provider owns its install questions (tty interactive
   // happens here, once). npx bin-name nuance (cf. the 0.2.9 update pitfall): with
   // the provider bin already on PATH npx runs the INSTALLED one — acceptable for
   // an idempotent init (unlike the self-update case where it was a structural bug).
-  const r = spawnSync('npx', ['-y', pkg, ...args], { stdio: 'inherit', env })
+  // timeout: a generous wall-clock backstop so a hung provider can't wedge onboard
+  // (the caller also makes Ctrl-C skip just this step).
+  const r = spawnSync('npx', ['-y', pkg, ...args], {
+    stdio: 'inherit',
+    env,
+    ...(timeoutMs ? { timeout: timeoutMs } : {}),
+  })
   return { status: r.status, unavailable: false }
 }
 
@@ -91,12 +113,12 @@ export async function onboardMemoryProvider(opts: MemoryOnboardOptions = {}): Pr
       detail: `slot is occupied by "${existing.provider}" (${existing.package}) — uninstall it first`,
     }
   }
-  const args = ['init', ...coreKnownInitArgs(env)]
+  const args = ['init', ...coreKnownInitArgs(env), ...(opts.runtime ? ['--runtime', opts.runtime] : [])]
   if (opts.dryRun) {
     return { state: 'dry-run', provider: null, detail: `would run: npx -y ${pkg} ${args.join(' ')}` }
   }
   const run = opts.runInit ?? defaultRunInit
-  const r = run(pkg, args, env)
+  const r = run(pkg, args, env, opts.timeoutMs)
   if (r.unavailable) {
     return {
       state: 'skipped-unavailable',

package/src/tui/onboard/app.tsx

@@ -20,15 +20,24 @@ export interface WizardResult {
   memoryConsent: boolean
   advisories: string[]
   summary: string[]
+  telegramConsent: boolean
+  /** Host agentic runtime detected during the run (claude if installed, else
+   *  codex, else undefined on a no-runtime host) — threaded to the memory
+   *  provider init as `--runtime` per the onboard↔init contract. */
+  hostRuntime?: OnboardRuntime
 }
 
-type Phase = 'gate' | 'running' | 'memory' | 'declined' | 'finishing'
+type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'declined' | 'finishing'
 type StepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'fail'
 interface Step {
   key: string
   label: string
   status: StepStatus
   detail?: string
+  /** Honest "this can take a moment" note shown while the step is running (the
+   *  spinner can't animate during a blocking spawnSync, so the label carries the
+   *  expectation). */
+  hint?: string
 }
 
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
@@ -85,6 +94,8 @@ export function OnboardApp({
   const [phase, setPhase] = useState<Phase>('gate')
   const [steps, setSteps] = useState<Step[]>([])
   const [advisories, setAdvisories] = useState<string[]>([])
+  const [hostRuntime, setHostRuntime] = useState<OnboardRuntime | undefined>(undefined)
+  const [telegramConsent, setTelegramConsent] = useState(false)
   const spin = useSpinnerFrame(phase === 'running')
 
   const finish = (memoryConsent: boolean): void => {
@@ -94,7 +105,7 @@ export function OnboardApp({
       return `  ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ''}`
     })
     summary.unshift(failed ? 'Onboard finished with errors:' : 'Onboard complete:')
-    onResult({ code: failed ? 1 : 0, memoryConsent, advisories, summary })
+    onResult({ code: failed ? 1 : 0, memoryConsent, telegramConsent, advisories, summary, hostRuntime })
     setPhase('finishing')
     setTimeout(() => exit(), 30)
   }
@@ -108,6 +119,22 @@ export function OnboardApp({
     { isActive: phase === 'gate' },
   )
 
+  // Telegram consent — DEFAULT-YES ([Y/n]). Records the decision; the actual setup
+  // (install + ask name/user_id) runs post-Ink (its readline needs a cooked
+  // terminal). Then → memory consent.
+  useInput(
+    (input, key) => {
+      if (input === 'n' || input === 'N') {
+        setTelegramConsent(false)
+        setPhase('memory')
+      } else if (input === 'y' || input === 'Y' || key.return) {
+        setTelegramConsent(true)
+        setPhase('memory')
+      }
+    },
+    { isActive: phase === 'telegram' },
+  )
+
   // Memory consent — DEFAULT-YES ([Y/n]: Enter or y → install).
   useInput(
     (input, key) => {
@@ -120,7 +147,7 @@ export function OnboardApp({
   // Declined → exit 1 (no host mutation).
   useEffect(() => {
     if (phase !== 'declined') return
-    onResult({ code: 1, memoryConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
+    onResult({ code: 1, memoryConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
     const t = setTimeout(() => exit(), 30)
     return () => clearTimeout(t)
   }, [phase, onResult, exit])
@@ -132,10 +159,16 @@ export function OnboardApp({
     const set = (k: string, patch: Partial<Step>) =>
       setSteps(prev => prev.map(s => (s.key === k ? { ...s, ...patch } : s)))
     setSteps([
-      { key: 'daemon', label: 'Start router daemon', status: 'pending' },
+      { key: 'daemon', label: 'Start router daemon', status: 'pending', hint: 'a few seconds' },
       { key: 'market', label: 'Register marketplace (claude, codex)', status: 'pending' },
       { key: 'auth', label: 'Check runtime sign-in', status: 'pending' },
       { key: 'fda', label: 'Check macOS Full Disk Access', status: 'pending' },
+      {
+        key: 'notifier',
+        label: 'Install scheduler (timer · watcher)',
+        status: 'pending',
+        hint: 'first run can take up to a minute',
+      },
     ])
 
     // Backend steps use synchronous spawnSync (launchctl, runtime plugin list) —
@@ -164,10 +197,19 @@ export function OnboardApp({
       const r = onboardHost({ env })
       const installed: OnboardRuntime[] = []
       for (const m of r.marketplaces) if (m.state !== 'runtime-missing') installed.push(m.runtime)
+      // host-runtime for the memory init contract: claude if present (covers
+      // both-installed → claude default), else codex, else undefined (no runtime).
+      setHostRuntime(installed.includes('claude') ? 'claude' : installed[0])
       const mFail = r.marketplaces.some(m => m.state === 'failed')
+      const allMissing = r.marketplaces.length > 0 && r.marketplaces.every(m => m.state === 'runtime-missing')
       set('market', {
-        status: mFail ? 'fail' : 'ok',
-        detail: r.marketplaces.map(m => `${m.runtime}:${m.state}`).join(' '),
+        // runtime-missing is NOT success — show '!' (warn), never a contradictory ✓.
+        status: mFail ? 'fail' : allMissing ? 'warn' : 'ok',
+        detail: allMissing
+          ? 'no agent runtime installed — skipped'
+          : r.marketplaces
+              .map(m => `${m.runtime}: ${m.state === 'runtime-missing' ? 'not installed' : m.state}`)
+              .join(', '),
       })
       if (cancelled) return
       await tick()
@@ -188,6 +230,7 @@ export function OnboardApp({
         })
         adv.push(...notes)
       }
+      setAdvisories([...adv]) // surface SETUP-INCOMPLETE / auth advisories IN the wizard now
       if (cancelled) return
 
       set('fda', { status: 'running' })
@@ -197,9 +240,32 @@ export function OnboardApp({
       set('fda', { status: tcc ? 'warn' : 'ok', detail: fda === true ? 'granted' : tcc ? 'not granted' : 'n/a' })
       if (tcc) adv.push(tcc)
       if (cancelled) return
+      await tick()
+
+      // notifier — the scheduler (timer · watcher) that memory's index upkeep
+      // rides on; a silent default. Its npx install captures stdio (no terminal
+      // contention), so it runs in-wizard like the other steps. Idempotent: a
+      // present package/peers → no-op. A failure must NOT fail onboard (degrade).
+      set('notifier', { status: 'running' })
+      await tick()
+      try {
+        // canonical backbone step (same as the linear onboard path): zero-question,
+        // captured-stdio, idempotent, soft-skip on unavailable.
+        const { onboardNotifierStep } = await import('../../onboard/steps.ts')
+        const ns = await onboardNotifierStep({ env, warn: () => {} })
+        set('notifier', {
+          status: ns.state === 'deployed' ? 'ok' : 'warn',
+          detail: ns.state === 'deployed' ? `${ns.peers.length} peer(s)` : (ns.detail ?? ns.state),
+        })
+        if (ns.state !== 'deployed') adv.push(`Scheduler (notifier): ${ns.detail ?? ns.state}`)
+      } catch (e) {
+        set('notifier', { status: 'warn', detail: (e instanceof Error ? e.message : 'failed').slice(0, 60) })
+      }
+      if (cancelled) return
+      await tick()
 
-      setAdvisories(adv)
-      setPhase('memory')
+      setAdvisories([...adv])
+      setPhase('telegram')
     })()
 
     return () => {
@@ -236,23 +302,51 @@ export function OnboardApp({
     return <Text color="red">onboard aborted — risk not accepted.</Text>
   }
 
-  // running | memory | finishing
+  // running | telegram | memory | finishing
   return (
     <Box flexDirection="column">
-      <Text bold>Setting up the host…</Text>
-      <Box flexDirection="column" marginTop={1}>
+      <Box marginBottom={1}>
+        <Text bold color="cyan">
+          iapeer
+        </Text>
+        <Text bold> · setting up the host</Text>
+      </Box>
+      <Box flexDirection="column">
         {steps.map(s => (
           <Box key={s.key}>
             <Text color={color(s.status)}>{glyph(s.status, spin)} </Text>
             <Text>{s.label}</Text>
-            {s.detail ? <Text dimColor> — {s.detail}</Text> : null}
+            {s.detail ? (
+              <Text dimColor> — {s.detail}</Text>
+            ) : s.status === 'running' && s.hint ? (
+              <Text dimColor> — {s.hint}…</Text>
+            ) : null}
           </Box>
         ))}
       </Box>
+      {advisories.length > 0 ? (
+        <Box marginTop={1} flexDirection="column" borderStyle="round" borderColor="yellow" paddingX={1}>
+          {advisories.map((a, i) => (
+            <Text key={i} color="yellow">
+              {a}
+            </Text>
+          ))}
+        </Box>
+      ) : null}
+      {phase === 'telegram' ? (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold color="cyan">
+            ? Set up Telegram — talk to your agents from your phone?
+          </Text>
+          <Text dimColor> It will ask your name + Telegram user_id next. (bot token comes later) [Y/n]</Text>
+        </Box>
+      ) : null}
       {phase === 'memory' ? (
         <Box marginTop={1} flexDirection="column">
-          <Text>Install the shared-memory provider (@agfpd/iapeer-memory)?</Text>
-          <Text dimColor>It gives your agents a shared knowledge vault. [Y/n] </Text>
+          <Text bold color="cyan">
+            ? Install the shared-memory provider (@agfpd/iapeer-memory)?
+          </Text>
+          <Text dimColor> Gives your agents a shared knowledge vault. [Y/n]</Text>
         </Box>
       ) : null}
     </Box>

package/src/tui/onboard/run.tsx

@@ -36,7 +36,7 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
     return WIZARD_NOT_INTERACTIVE
   }
 
-  let result: WizardResult = { code: 0, memoryConsent: false, advisories: [], summary: [] }
+  let result: WizardResult = { code: 0, memoryConsent: false, telegramConsent: false, advisories: [], summary: [] }
   try {
     const app = render(<OnboardApp env={env} onResult={r => (result = r)} />)
     await app.waitUntilExit()
@@ -44,20 +44,52 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
     return WIZARD_NOT_INTERACTIVE
   }
 
-  // Post-Ink: the memory provider install owns the terminal (inherited stdio).
-  // Ink is fully unmounted now, so there is no contention.
-  if (result.memoryConsent) {
-    const { onboardMemoryProvider } = await import('../../onboard/memory.ts')
-    process.stdout.write('\nInstalling shared-memory provider (@agfpd/iapeer-memory)…\n')
-    try {
-      const mem = await onboardMemoryProvider({ env })
-      const label = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
-      process.stdout.write(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${label})\n`)
-    } catch (e) {
-      process.stdout.write(`memory: step failed — ${e instanceof Error ? e.message : String(e)}\n`)
+  // Post-Ink interactive provisioning — telegram THEN memory (the canonical order:
+  // telegram creates the human peer that memory's --human resolves from). These own
+  // the terminal (inherited stdio / readline), so they run AFTER Ink unmounts (no
+  // contention). NON-WEDGE: ignore SIGINT in the parent so Ctrl-C kills only the
+  // CURRENT step's child/readline and onboard continues to the summary, instead of
+  // the whole flow dying. The no-op handler is queued past the blocking spawnSync.
+  const prevInt = process.listeners('SIGINT')
+  process.removeAllListeners('SIGINT')
+  const ignore = (): void => {}
+  process.on('SIGINT', ignore)
+  try {
+    if (result.telegramConsent) {
+      const { onboardTelegramStep } = await import('../../onboard/steps.ts')
+      process.stdout.write('\nSetting up Telegram… (Ctrl-C to skip — add later: `iapeer create <you> --runtime telegram`)\n')
+      try {
+        const ts = await onboardTelegramStep({ env })
+        process.stdout.write(`telegram: ${ts.state}${ts.detail ? ` — ${ts.detail}` : ''}\n`)
+      } catch (e) {
+        process.stdout.write(`telegram: step skipped — ${e instanceof Error ? e.message : String(e)}\n`)
+      }
+    } else {
+      process.stdout.write('\ntelegram: skipped — add later with `iapeer create <you> --runtime telegram`\n')
+    }
+
+    if (result.memoryConsent) {
+      const { onboardMemoryProvider } = await import('../../onboard/memory.ts')
+      process.stdout.write(
+        '\nInstalling the shared-memory provider (@agfpd/iapeer-memory)…\n' +
+          'This can take a few minutes — it builds a native module. Memory is OPTIONAL:\n' +
+          'press Ctrl-C to skip it (set it up later with `npx @agfpd/iapeer-memory init`).\n\n',
+      )
+      try {
+        const mem = await onboardMemoryProvider({ env, runtime: result.hostRuntime, timeoutMs: 12 * 60_000 })
+        const label = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
+        process.stdout.write(`\nmemory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${label})\n`)
+      } catch (e) {
+        process.stdout.write(
+          `\nmemory: step skipped — ${e instanceof Error ? e.message : String(e)} (set up later: \`npx @agfpd/iapeer-memory init\`)\n`,
+        )
+      }
+    } else {
+      process.stdout.write('\nmemory: skipped — set it up later with `npx @agfpd/iapeer-memory init`\n')
     }
-  } else {
-    process.stdout.write('\nmemory: skipped — set it up later with `iapeer onboard` or `npx @agfpd/iapeer-memory init`\n')
+  } finally {
+    process.removeListener('SIGINT', ignore)
+    for (const h of prevInt) process.on('SIGINT', h as NodeJS.SignalsListener)
   }
 
   // Final summary (plain text, post-Ink).
@@ -67,6 +99,12 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
     process.stdout.write('\n')
     for (const a of result.advisories) process.stdout.write(a + '\n')
   }
-  process.stdout.write('\nNext: create your first agent — `iapeer create <name> --runtime claude`\n')
+  process.stdout.write('\nNext steps:\n')
+  process.stdout.write('  • Create your first agent:  iapeer create <name> --runtime claude\n')
+  if (result.telegramConsent) {
+    // The wizard set up the human peer (name + user_id) but NOT the bot itself —
+    // the bot token is a separate, explicit step (no surprise / don't-make-them-guess).
+    process.stdout.write('  • Activate Telegram:        iapeer connect telegram   (paste a bot token from @BotFather)\n')
+  }
   return result.code
 }

package/src/uninstall/index.ts

@@ -0,0 +1,244 @@
+// uninstall — symmetric removal of THIS foundation install (the install.sh / `iapeer
+// install` / onboard artifacts). NAMESPACE-SAFE: it never touches a foreign
+// persistent-peer fleet. A peer plist at the shared `com.iapeer.*` namespace WITHOUT
+// the ownership sentinel is foreign; if ANY is present we REFUSE (option-1) — removing
+// ~/.iapeer would nuke the fleet's own state, which H4 forbids. The operator removes
+// their peers first (`iapeer remove <p>`), then uninstalls.
+//
+// Removed: ~/.local/bin/iapeer (+ .prev) · the daemon plist (com.agfpd.iapeer,
+// bootout→rm) · foundation-OWNED infra jobs (sentinel-marked com.iapeer.*, bootout→rm)
+// · the ~/.iapeer scaffold · the installer's PATH lines in the shell profile.
+// CONSERVATIVE (kept by default): the shared agfpd-stack codesign identity (removed
+// only with removeCodesignIdentity) and bun (the user's). Plan is read-only — `--dry-run`
+// renders it without touching anything. Fail-closed in the test sandbox: a real
+// ~/.iapeer / ~/.local/bin path under IAPEER_TEST_SANDBOX=1 throws (tests must inject
+// temp roots), so a hermetic test can never delete the real install.
+
+import { spawnSync } from 'child_process'
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { DAEMON_PLIST_LABEL, IapError } from '../core/index.ts'
+import { iapeerBinPath } from '../install/index.ts'
+import { SIGNING_IDENTITY_CN } from '../install/signing.ts'
+import { daemonPlistPath } from '../daemon/main.ts'
+import { isFoundationOwnedPlist, launchAgentsDir } from '../launch/launchd.ts'
+import { resolveGlobalRoot } from '../storage/index.ts'
+
+/** The marker comment install.sh writes above its PATH line (strip both lines). */
+const INSTALLER_PROFILE_MARKER = '# Added by the iapeer installer'
+
+export type UninstallActionKind =
+  | 'remove-file'
+  | 'remove-dir'
+  | 'bootout-remove-plist'
+  | 'strip-profile-lines'
+  | 'remove-keychain-identity'
+
+export interface UninstallItem {
+  what: string
+  action: UninstallActionKind
+  path?: string
+  /** True when the artifact exists / there is something to do (dry-run shows all;
+   *  absent ones render as "already gone"). */
+  present: boolean
+  detail?: string
+}
+
+export interface UninstallPlan {
+  items: UninstallItem[]
+  /** Set when a FOREIGN persistent-peer fleet is present → the whole uninstall is
+   *  refused (option-1, H4-safe). The caller prints the guidance and aborts. */
+  refused?: { reason: string; foreignLabels: string[] }
+}
+
+/** Injected launchctl/security runner (tests). Default: real spawnSync. */
+export type SysRunner = (cmd: string, args: string[]) => { status: number | null; stderr: string }
+
+export interface UninstallOptions {
+  env?: NodeJS.ProcessEnv
+  /** --remove-codesign-identity: also delete the SHARED agfpd-stack signing identity. */
+  removeCodesignIdentity?: boolean
+  /** Injected sys runner (launchctl / security) for hermetic tests. */
+  run?: SysRunner
+}
+
+const defaultRun: SysRunner = (cmd, args) => {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return { status: r.status, stderr: (r.stderr ?? '').trim() }
+}
+
+function home(env: NodeJS.ProcessEnv): string {
+  return env.HOME?.trim() || homedir()
+}
+
+/** Shell-profile files the installer may have edited (per its $SHELL branch). */
+function profileFiles(env: NodeJS.ProcessEnv): string[] {
+  const h = home(env)
+  return [join(h, '.zshrc'), join(h, '.bash_profile'), join(h, '.profile')]
+}
+
+/** All com.iapeer.*.plist in LaunchAgents, split into foundation-owned (sentinel)
+ *  vs foreign (the persistent-peer fleet). */
+function scanInfraPlists(env: NodeJS.ProcessEnv): { owned: string[]; foreign: string[] } {
+  const dir = launchAgentsDir(env)
+  const owned: string[] = []
+  const foreign: string[] = []
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return { owned, foreign }
+  }
+  for (const e of entries) {
+    if (!e.startsWith('com.iapeer.') || !e.endsWith('.plist')) continue
+    const p = join(dir, e)
+    ;(isFoundationOwnedPlist(p) ? owned : foreign).push(p)
+  }
+  return { owned, foreign }
+}
+
+/** Fail-closed: under the test sandbox, refuse to operate on the REAL install paths
+ *  (a hermetic test MUST inject temp roots). Mirrors installIapeer's guard. */
+function assertSandboxSafe(env: NodeJS.ProcessEnv): void {
+  if (env.IAPEER_TEST_SANDBOX !== '1' && process.env.IAPEER_TEST_SANDBOX !== '1') return
+  const root = resolveGlobalRoot(env)
+  const realRoot = join(homedir(), '.iapeer')
+  const bin = iapeerBinPath(env)
+  const realBin = join(homedir(), '.local', 'bin', 'iapeer')
+  if (root === realRoot || bin === realBin) {
+    throw new IapError(
+      'refusing to uninstall the REAL install under IAPEER_TEST_SANDBOX=1 — inject IAPEER_ROOT / IAPEER_BIN_DIR temp paths',
+    )
+  }
+}
+
+/** Read-only: compute what an uninstall would remove + the foreign-fleet refusal. */
+export function planUninstall(opts: UninstallOptions = {}): UninstallPlan {
+  const env = opts.env ?? process.env
+  const { owned, foreign } = scanInfraPlists(env)
+
+  if (foreign.length > 0) {
+    const foreignLabels = foreign.map(p => p.replace(/\.plist$/, '').split('/').pop() ?? p)
+    return {
+      items: [],
+      refused: {
+        foreignLabels,
+        reason:
+          `persistent-peer fleet present (${foreignLabels.join(', ')}). Removing ~/.iapeer would ` +
+          `destroy their state. Remove those peers first (\`iapeer remove <peer>\`), then re-run uninstall.`,
+      },
+    }
+  }
+
+  const bin = iapeerBinPath(env)
+  const prev = `${bin}.prev`
+  const dPlist = daemonPlistPath(env)
+  const root = resolveGlobalRoot(env)
+  const items: UninstallItem[] = []
+
+  // launchd: daemon first, then foundation-owned infra jobs (bootout → rm).
+  items.push({
+    what: `daemon job ${DAEMON_PLIST_LABEL}`,
+    action: 'bootout-remove-plist',
+    path: dPlist,
+    present: existsSync(dPlist),
+  })
+  for (const p of owned) {
+    items.push({
+      what: `infra job ${p.replace(/\.plist$/, '').split('/').pop()}`,
+      action: 'bootout-remove-plist',
+      path: p,
+      present: true,
+    })
+  }
+
+  items.push({ what: 'binary ~/.local/bin/iapeer', action: 'remove-file', path: bin, present: existsSync(bin) })
+  items.push({ what: 'previous binary (.prev)', action: 'remove-file', path: prev, present: existsSync(prev) })
+  items.push({ what: 'state + config ~/.iapeer', action: 'remove-dir', path: root, present: existsSync(root) })
+
+  for (const pf of profileFiles(env)) {
+    const has = existsSync(pf) && readFileSync(pf, 'utf8').includes(INSTALLER_PROFILE_MARKER)
+    if (has) items.push({ what: `PATH line in ${pf}`, action: 'strip-profile-lines', path: pf, present: true })
+  }
+
+  items.push({
+    what: `codesign identity "${SIGNING_IDENTITY_CN}"`,
+    action: 'remove-keychain-identity',
+    present: opts.removeCodesignIdentity === true,
+    detail: opts.removeCodesignIdentity
+      ? 'will remove (shared agfpd-stack identity — other agfpd products re-prompt on next update)'
+      : 'KEPT (shared agfpd-stack identity) — pass --remove-codesign-identity to remove',
+  })
+
+  return { items }
+}
+
+export interface UninstallResult {
+  removed: string[]
+  skipped: string[]
+  failed: { what: string; detail: string }[]
+  refused?: { reason: string; foreignLabels: string[] }
+}
+
+/** Remove a foundation install per the plan. Refuses if a foreign fleet is present. */
+export function executeUninstall(opts: UninstallOptions = {}): UninstallResult {
+  const env = opts.env ?? process.env
+  assertSandboxSafe(env)
+  const run = opts.run ?? defaultRun
+  const plan = planUninstall(opts)
+  const res: UninstallResult = { removed: [], skipped: [], failed: [] }
+  if (plan.refused) {
+    res.refused = plan.refused
+    return res
+  }
+
+  const uid = process.getuid?.() ?? 0
+  for (const item of plan.items) {
+    if (!item.present) {
+      res.skipped.push(item.what)
+      continue
+    }
+    try {
+      switch (item.action) {
+        case 'bootout-remove-plist': {
+          const label = (item.path ?? '').replace(/\.plist$/, '').split('/').pop() ?? ''
+          run('launchctl', ['bootout', `gui/${uid}/${label}`]) // best-effort (not-loaded → non-zero, fine)
+          if (item.path) rmSync(item.path, { force: true })
+          break
+        }
+        case 'remove-file':
+          if (item.path) rmSync(item.path, { force: true })
+          break
+        case 'remove-dir':
+          if (item.path) rmSync(item.path, { recursive: true, force: true })
+          break
+        case 'strip-profile-lines':
+          if (item.path) stripInstallerLines(item.path)
+          break
+        case 'remove-keychain-identity':
+          run('security', ['delete-identity', '-c', SIGNING_IDENTITY_CN])
+          break
+      }
+      res.removed.push(item.what)
+    } catch (e) {
+      res.failed.push({ what: item.what, detail: e instanceof Error ? e.message : String(e) })
+    }
+  }
+  return res
+}
+
+/** Remove the installer's marker comment + the export PATH line it precedes. */
+function stripInstallerLines(profile: string): void {
+  const lines = readFileSync(profile, 'utf8').split('\n')
+  const out: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]?.trim() === INSTALLER_PROFILE_MARKER) {
+      // skip the marker AND the following export PATH line the installer wrote
+      if (lines[i + 1]?.includes('.local/bin')) i++
+      continue
+    }
+    out.push(lines[i]!)
+  }
+  writeFileSync(profile, out.join('\n'), { mode: 0o644 })
+}