@agfpd/iapeer 0.2.35 → 0.2.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "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)