@agfpd/iapeer 0.2.35 → 0.2.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -1129,7 +1129,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         const { installIapeer } = await import('../install/index.ts')
         ensureGlobalIapScaffold({ env })
         const r = installIapeer(fileURLToPath(import.meta.url), env)
-        const plist = installDaemonPlist({ env })
+        const { path: plist, changed: plistChanged } = installDaemonPlist({ env })
         const signingLine =
           r.signing == null
             ? ''
@@ -1142,7 +1142,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             `${r.size ? ` (${Math.round(r.size / 1e6)}M)` : ''}\n` +
             signingLine +
             `  scaffold: ~/.iapeer/ ensured (peers/, state, logs, cache, runtimes)\n` +
-            `  daemon plist written: ${plist}\n` +
+            `  daemon plist ${plistChanged ? 'written' : 'unchanged (byte-identical — no write, no BTM notification)'}: ${plist}\n` +
             `  (NOT loaded — a live daemon migration is a separate step: launchctl bootstrap gui/$(id -u) ${plist})\n`,
         )
         return 0
@@ -1151,8 +1151,8 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Ф-F: the prod daemon entrypoint. The launchd plist runs `iapeer daemon`
         // (the INSTALLED binary), decoupling prod from the mutable src tree.
         if (flags['install-plist'] === true) {
-          const p = installDaemonPlist({ env })
-          out(`installed daemon plist: ${p}\nNOT loaded — to start: launchctl bootstrap gui/$(id -u) ${p}\n`)
+          const { path: p, changed } = installDaemonPlist({ env })
+          out(`daemon plist ${changed ? 'written' : 'unchanged'}: ${p}\nNOT loaded — to start: launchctl bootstrap gui/$(id -u) ${p}\n`)
           return 0
         }
         const handle = await startConfiguredDaemon({

package/src/daemon/main.test.ts

@@ -75,17 +75,40 @@ describe('buildDaemonPlistSpec / installDaemonPlist (com.agfpd.iapeer)', () => {
       HOME: root,
       PATH: '/usr/bin:/bin',
     } as NodeJS.ProcessEnv
-    const path = installDaemonPlist({ env, port: 8765, throttleIntervalSecs: 10 })
-    expect(path).toBe(daemonPlistPath(env))
-    expect(existsSync(path)).toBe(true)
-    expect(isFoundationOwnedPlist(path)).toBe(true)
-    expect(plutilLint(path)).toBe(true) // live plutil: valid plist
-    const xml = readFileSync(path, 'utf8')
+    const r = installDaemonPlist({ env, port: 8765, throttleIntervalSecs: 10 })
+    expect(r.path).toBe(daemonPlistPath(env))
+    expect(r.changed).toBe(true) // first install on a clean host writes
+    expect(existsSync(r.path)).toBe(true)
+    expect(isFoundationOwnedPlist(r.path)).toBe(true)
+    expect(plutilLint(r.path)).toBe(true) // live plutil: valid plist
+    const xml = readFileSync(r.path, 'utf8')
     expect(xml).toContain(`<string>${DAEMON_PLIST_LABEL}</string>`)
     expect(xml).toContain('<key>RunAtLoad</key>')
     expect(xml).toContain('<key>KeepAlive</key>')
   })
 
+  test('idempotent by content: a re-install of the SAME plist does NOT rewrite the file (changed:false, mtime stable) — no BTM notification spam (owner-caught 11.06)', () => {
+    const root = mkTmp()
+    const env = {
+      IAPEER_LAUNCHAGENTS_DIR: join(root, 'LaunchAgents'),
+      IAPEER_ROOT: join(root, 'iapeer'),
+      HOME: root,
+      PATH: '/usr/bin:/bin',
+    } as NodeJS.ProcessEnv
+    const opts = { env, port: 8765, throttleIntervalSecs: 10 }
+    const first = installDaemonPlist(opts)
+    expect(first.changed).toBe(true)
+    const mtime1 = statSync(first.path).mtimeMs
+    // second identical install — must be a pure no-op (no write → BTM not tripped)
+    const second = installDaemonPlist(opts)
+    expect(second.changed).toBe(false)
+    expect(second.path).toBe(first.path)
+    expect(statSync(second.path).mtimeMs).toBe(mtime1) // file untouched, not just byte-equal
+    // a CHANGED spec (different port → different rendered plist) DOES rewrite
+    const third = installDaemonPlist({ env, port: 9999, throttleIntervalSecs: 10 })
+    expect(third.changed).toBe(true)
+  })
+
   test('REFUSES to overwrite a foreign com.agfpd.iapeer.plist (collision guard)', () => {
     const root = mkTmp()
     const laDir = join(root, 'LaunchAgents')
@@ -96,6 +119,8 @@ describe('buildDaemonPlistSpec / installDaemonPlist (com.agfpd.iapeer)', () => {
     writeFileSync(path, foreign)
     expect(() => installDaemonPlist({ env })).toThrow(/foundation-managed|refus/i)
     expect(readFileSync(path, 'utf8')).toBe(foreign) // untouched
+    // (the throw must fire BEFORE the write-if-changed read, so the foreign file
+    //  is never even compared — the guard is the first gate.)
   })
 })
 

package/src/daemon/main.ts

@@ -15,7 +15,7 @@
 // action (`--install-plist`); it writes the file but does NOT load it — a live
 // `launchctl bootstrap` stays a deliberate operator step.
 
-import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
@@ -301,17 +301,33 @@ export function buildDaemonPlistSpec(opts: InstallDaemonPlistOptions = {}): Laun
   }
 }
 
+export interface InstallDaemonPlistResult {
+  /** The plist path (always returned, written or not). */
+  path: string
+  /** false when the on-disk plist already matched byte-for-byte → NO write was
+   *  done. The deploy path calls this on EVERY `iapeer update`; a byte-identical
+   *  rewrite serves nothing (the daemon never re-reads the file — launchd holds
+   *  its loaded definition; a changed file takes effect only on an explicit
+   *  bootout+bootstrap) yet each write into ~/Library/LaunchAgents trips macOS
+   *  Background Task Management → a "background activity" notification to the
+   *  owner on every deploy. Skipping the no-op write suppresses that noise. */
+  changed: boolean
+}
+
 /**
  * Generate + install the daemon's always-on launchd plist at
  * ~/Library/LaunchAgents/com.agfpd.iapeer.plist (or IAPEER_LAUNCHAGENTS_DIR),
- * returning the path. Writes the FILE only — does NOT bootstrap it (load is a
- * deliberate operator step). Collision guard: refuses to overwrite an existing
- * com.agfpd.iapeer.plist that is not foundation-owned (lacks the sentinel) — the
- * same ownership proof the peer-plist installer uses. com.agfpd.* is the
- * foundation-exclusive daemon namespace, so this never touches the com.iapeer.*
- * persistent-peer fleet.
+ * returning {path, changed}. Writes the FILE only — does NOT bootstrap it (load
+ * is a deliberate operator step). IDEMPOTENT BY CONTENT: writes only when the
+ * rendered plist differs from what is already on disk (owner-caught 11.06: an
+ * unconditional rewrite on every deploy spams the owner's Background Task
+ * Management notification for zero benefit). Collision guard: refuses to
+ * overwrite an existing com.agfpd.iapeer.plist that is not foundation-owned
+ * (lacks the sentinel) — the same ownership proof the peer-plist installer uses.
+ * com.agfpd.* is the foundation-exclusive daemon namespace, so this never
+ * touches the com.iapeer.* persistent-peer fleet.
  */
-export function installDaemonPlist(opts: InstallDaemonPlistOptions = {}): string {
+export function installDaemonPlist(opts: InstallDaemonPlistOptions = {}): InstallDaemonPlistResult {
   const env = opts.env ?? process.env
   const path = daemonPlistPath(env)
   if (existsSync(path) && !isFoundationOwnedPlist(path)) {
@@ -320,11 +336,20 @@ export function installDaemonPlist(opts: InstallDaemonPlistOptions = {}): string
         `(no ownership sentinel) — another manager owns it`,
     )
   }
-  const spec = buildDaemonPlistSpec(opts)
+  const rendered = renderLaunchdPlist(buildDaemonPlistSpec(opts))
   mkdirSync(launchAgentsDir(env), { recursive: true })
   mkdirSync(pluginLogsDir('iapeer', { env }), { recursive: true, mode: 0o700 })
-  writeFileSync(path, renderLaunchdPlist(spec), { mode: 0o644 })
-  return path
+  // Write-if-changed: a byte-identical rewrite is a pure no-op for the daemon but
+  // trips the owner's BTM notification — skip it (see InstallDaemonPlistResult).
+  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 }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -337,9 +362,9 @@ if (import.meta.main) {
     process.stdout.write(renderLaunchdPlist(buildDaemonPlistSpec()))
     process.exit(0)
   } else if (arg === '--install-plist') {
-    const p = installDaemonPlist()
+    const { path: p, changed } = installDaemonPlist()
     process.stdout.write(
-      `installed daemon plist: ${p}\n` +
+      `daemon plist ${changed ? 'written' : 'unchanged'}: ${p}\n` +
         `NOT loaded. To start it live: launchctl bootstrap gui/$(id -u) ${p}\n`,
     )
     process.exit(0)

package/src/status/index.ts

@@ -6,12 +6,13 @@
 // error (fail-open). The core never acts on heartbeat staleness — it only REPORTS
 // it (healing the provider's daemon is the provider's job, their ADR-010).
 
-import { readFileSync, statSync } from 'fs'
+import { closeSync, openSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { IAPEER_VERSION } from '../core/version.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import { daemonDiscoveryPath } from '../daemon/index.ts'
 import { waitForDaemonHealthy } from '../update/index.ts'
+import { iapeerBinPath } from '../install/index.ts'
 
 /** The slot-declaration filename in the storage root (next to peers-profiles.json). */
 export const MEMORY_PROVIDER_FILE = 'memory-provider.json'
@@ -135,16 +136,48 @@ export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.
   }
 }
 
+/**
+ * Probe whether the iapeer binary holds Full Disk Access (macOS TCC). Reads the
+ * user TCC.db — a canonical FDA-gated resource that is NEVER promptable (silent
+ * EPERM without the grant), so THE PROBE ITSELF raises no dialog (it must not be
+ * the very noise it detects). Byte-free: open+close to prove access, no content
+ * read. Returns:
+ *   true  — readable → FDA granted
+ *   false — EPERM/EACCES → FDA NOT granted (peers will hit TCC prompts on
+ *           protected folders + foreign app containers — see onboard contract)
+ *   null  — not macOS / no HOME / TCC.db absent → cannot determine (no claim)
+ */
+export function probeFullDiskAccess(env: NodeJS.ProcessEnv = process.env): boolean | null {
+  if (process.platform !== 'darwin') return null
+  const home = env.HOME
+  if (!home) return null
+  const marker = join(home, 'Library', 'Application Support', 'com.apple.TCC', 'TCC.db')
+  try {
+    closeSync(openSync(marker, 'r'))
+    return true
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code
+    if (code === 'EPERM' || code === 'EACCES') return false
+    return null // ENOENT / unexpected → undeterminable, never a false claim
+  }
+}
+
 export interface HostStatus {
   version: string
   daemon: { healthy: boolean; url: string | null; sock: string | null }
   memory: { provider: MemoryProvider | null; heartbeatAgeSecs: number | null }
+  /** Full Disk Access of the iapeer binary: true granted / false not-granted /
+   *  null undeterminable (non-macOS or TCC.db unreadable for a non-TCC reason). */
+  fda: boolean | null
 }
 
 export interface HostStatusOptions {
   env?: NodeJS.ProcessEnv
   /** Injectable daemon probe (tests). Default: the real socket probe. */
   probe?: () => Promise<boolean>
+  /** Injectable FDA probe (tests — the default reads the real TCC.db, which a
+   *  hermetic test must not touch). Default: probeFullDiskAccess(env). */
+  fdaProbe?: () => boolean | null
 }
 
 /** Assemble the host snapshot: baked version + daemon probe + memory slot. */
@@ -161,10 +194,12 @@ export async function hostStatus(opts: HostStatusOptions = {}): Promise<HostStat
   }
   const health = await waitForDaemonHealthy({ env, timeoutMs: 2500, needConsecutive: 1, probe: opts.probe })
   const provider = readMemoryProvider(env)
+  const fda = (opts.fdaProbe ?? (() => probeFullDiskAccess(env)))()
   return {
     version: IAPEER_VERSION,
     daemon: { healthy: health.healthy, url, sock },
     memory: { provider, heartbeatAgeSecs: provider ? heartbeatAgeSecs(provider) : null },
+    fda,
   }
 }
 
@@ -184,5 +219,19 @@ export function formatHostStatus(s: HostStatus): string {
       : ' (daemon not running — no heartbeat file)'
   }
   const memory = s.memory.provider ? `${s.memory.provider.provider} ${s.memory.provider.version}${hb}` : 'none'
-  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n`
+  // FDA line: granted → terse OK; NOT granted → the actionable hint (a fresh host
+  // without FDA silently meets TCC prompts on every new protected class — peers
+  // read protected folders + foreign app containers, attributed to this binary;
+  // see onboard contract §INSTALL). undeterminable → say so, never a false claim.
+  let fda: string
+  if (s.fda === true) {
+    fda = 'fda: granted'
+  } else if (s.fda === false) {
+    fda =
+      `fda: NOT granted — peers will hit TCC prompts on protected paths.\n` +
+      `  grant: System Settings → Privacy & Security → Full Disk Access → + → ⇧⌘G → ${iapeerBinPath()}`
+  } else {
+    fda = 'fda: unknown (not macOS / undeterminable)'
+  }
+  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n${fda}\n`
 }

package/src/status/status.test.ts

@@ -128,7 +128,7 @@ describe('heartbeatAgeSecs', () => {
 describe('hostStatus + formatHostStatus', () => {
   test('empty slot → memory: none; daemon health from the injected probe', async () => {
     const root = mkTmp()
-    const s = await hostStatus({ env: envFor(root), probe: async () => true })
+    const s = await hostStatus({ env: envFor(root), probe: async () => true, fdaProbe: () => null })
     expect(s.daemon.healthy).toBe(true)
     expect(s.memory.provider).toBeNull()
     expect(formatHostStatus(s)).toContain('memory: none')
@@ -140,7 +140,7 @@ describe('hostStatus + formatHostStatus', () => {
     const hb = join(root, 'memoryd.heartbeat')
     writeFileSync(hb, '')
     writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, heartbeat: hb }))
-    const s = await hostStatus({ env, probe: async () => true })
+    const s = await hostStatus({ env, probe: async () => true, fdaProbe: () => null })
     expect(formatHostStatus(s)).toMatch(/memory: iapeer-memory 0\.1\.0 \(heartbeat \d+s ago\)/)
   })
 
@@ -152,6 +152,7 @@ describe('hostStatus + formatHostStatus', () => {
         provider: { ...VALID, heartbeat: '/nope/hb' } as MemoryProvider,
         heartbeatAgeSecs: null,
       },
+      fda: null,
     }
     const text = formatHostStatus(s)
     expect(text).toContain('memory: iapeer-memory 0.1.0 (daemon not running — no heartbeat file)')
@@ -164,9 +165,48 @@ describe('hostStatus + formatHostStatus', () => {
     const stateDir = join(root, 'state', 'iapeer')
     mkdirSync(stateDir, { recursive: true })
     writeFileSync(join(stateDir, 'router.json'), JSON.stringify({ sock: '/x/router.sock', tcp: 'http://127.0.0.1:8765/mcp' }))
-    const s = await hostStatus({ env, probe: async () => true })
+    const s = await hostStatus({ env, probe: async () => true, fdaProbe: () => null })
     const text = formatHostStatus(s)
     expect(text).toContain('@ http://127.0.0.1:8765/mcp')
     expect(text).toContain('+ /x/router.sock')
   })
 })
+
+describe('FDA detection (iapeer status — fresh-host observability)', () => {
+  function base(fda: boolean | null): HostStatus {
+    return {
+      version: '0.0.0',
+      daemon: { healthy: true, url: null, sock: null },
+      memory: { provider: null, heartbeatAgeSecs: null },
+      fda,
+    }
+  }
+
+  test('granted → terse OK line, no instruction', () => {
+    const text = formatHostStatus(base(true))
+    expect(text).toContain('fda: granted')
+    expect(text).not.toContain('NOT granted')
+    expect(text).not.toContain('Full Disk Access')
+  })
+
+  test('NOT granted → actionable hint with the binary path', () => {
+    const text = formatHostStatus(base(false))
+    expect(text).toContain('fda: NOT granted')
+    expect(text).toContain('Full Disk Access')
+    expect(text).toMatch(/iapeer$|iapeer\n/m) // the grant path ends at the binary
+  })
+
+  test('undeterminable → explicit unknown, never a false claim', () => {
+    const text = formatHostStatus(base(null))
+    expect(text).toContain('fda: unknown')
+    expect(text).not.toContain('NOT granted')
+    expect(text).not.toContain('granted\n') // not the bare "granted" either
+  })
+
+  test('hostStatus threads the injected fdaProbe verbatim', async () => {
+    const root = mkTmp()
+    const s = await hostStatus({ env: envFor(root), probe: async () => true, fdaProbe: () => false })
+    expect(s.fda).toBe(false)
+    expect(formatHostStatus(s)).toContain('fda: NOT granted')
+  })
+})