@agfpd/iapeer 0.2.34 → 0.2.35

package/package.json

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

package/src/cli/cli.test.ts

@@ -145,6 +145,29 @@ describe('stop / start (C1 durable flag, warm runtime)', () => {
     expect(isStopped(cfg, 'claude-parked')).toBe(false)
     expect(hasIdleReaped(cfg, 'claude-parked')).toBe(true)
   })
+  test('start --all clears the flag of EVERY registered peer; unregistered garbage untouched (incident 11.06)', async () => {
+    await register('p1')
+    await register('p2')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    // a stopped fleet …
+    setStopped(cfg, 'claude-p1')
+    setStopped(cfg, 'claude-p2')
+    // … plus a stray stop-flag for an identity NO registry record claims
+    setStopped(cfg, 'claude-ghost')
+    expect(await runCli(['start', '--all'], e)).toBe(0)
+    expect(isStopped(cfg, 'claude-p1')).toBe(false)
+    expect(isStopped(cfg, 'claude-p2')).toBe(false)
+    expect(isStopped(cfg, 'claude-ghost')).toBe(true) // unregistered → never enumerated, never touched
+  })
+  test('start without a peer and without --all → usage, nothing executed', async () => {
+    await register('p3')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    setStopped(cfg, 'claude-p3')
+    expect(await runCli(['start'], e)).toBe(2)
+    expect(isStopped(cfg, 'claude-p3')).toBe(true) // flag untouched — usage only
+  })
 })
 
 describe('FLEET GUARD (H4) — foreign persistent-peer launchd plist is off-limits', () => {

package/src/cli/index.ts

@@ -445,7 +445,7 @@ export async function sendMessage(
   // unawaited in-process wake would die with it; the daemon's supervise-tick
   // drain scan (≤60 s) picks the queue up — the EXISTING retry path for failed
   // kicks, not a new mechanism.
-  const { makeArmEphemeralOnDelivered, makeEphemeralRouteDeps } = await import('../daemon/main.ts')
+  const { makeArmEphemeralOnDelivered, makeEphemeralRouteDeps, makeNoteLiveTopic } = await import('../daemon/main.ts')
   const cfg = loadLifecycleConfig(env)
   const t0 = Date.now()
   const result = await routeSend(
@@ -457,7 +457,10 @@ export async function sendMessage(
       topic: opts.topic,
       attachments: opts.attachments,
     },
-    { wake: cliWake, ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}) },
+    // noteLiveTopic — CLI-path parity (same seam the daemon wires): a live delivery
+    // through the CLI fallback must update the target's .topic marker too, or a
+    // daemon-restart-window send re-opens the stale-marker false-fresh (defect 11.06).
+    { wake: cliWake, ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}), noteLiveTopic: makeNoteLiveTopic(cfg, env) },
   )
   // delivery.log sink — CLI-path parity (boris's observability gap 10.06: enqueues
   // routed through the CLI left to=<peer> at ZERO for the day while real wakes
@@ -552,8 +555,10 @@ const USAGE = `usage: iapeer <verb> [args]
   create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
   list [--json]                                                  registered peers + per-runtime liveness
   verify [--json] [--fix]                                        profile-standard conformance + index↔local drift (--fix self-heals the index)
-  stop <peer> [runtime] | --all                                  durable-stop a warm peer / bootout an always-on one
-  start <peer> [runtime]                                         re-enable a stopped peer / bootstrap an always-on one
+  stop <peer> [runtime] | --all                                  warm peer: kill the live session + set a durable stop-flag — the daemon will NOT wake it
+                                                                 until \`start\`; always-on (notifier/telegram): launchctl bootout. --all = every registered peer
+  start <peer> [runtime] | --all                                 warm peer: clear the stop-flag — wakeable again; does NOT launch a session (the daemon brings
+                                                                 it up on the peer's first message); always-on: launchctl bootstrap. --all = every registered peer
   remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
   send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]   manual IAP send (fallback)
   <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
@@ -948,8 +953,19 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
       }
       case 'start': {
-        if (!positionals[0]) return usage(errOut)
-        const outcomes = startPeer(positionals[0], positionals[1], { env })
+        // --all re-enables every REGISTERED peer (mirror of `stop --all` — the 11.06
+        // incident: bringing a stopped fleet back required a manual loop over ~25
+        // peers). Enumeration is the registry, so unregistered garbage (stray flag
+        // files for identities no record claims) is never touched. NOTE: for warm
+        // peers this clears the stop flag only — no session is launched; each peer
+        // becomes wakeable and the daemon brings its session up on the first message.
+        const peers = flags.all === true
+          ? readPeersIndex({ env }).peers.map(p => p.personality)
+          : positionals[0]
+            ? [positionals[0]]
+            : null
+        if (!peers) return usage(errOut)
+        const outcomes = peers.flatMap(p => startPeer(p, flags.all === true ? undefined : positionals[1], { env }))
         for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
         return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
       }

package/src/daemon/index.ts

@@ -188,6 +188,10 @@ export interface CallToolDeps {
   onDelivered?: (caller: ResolvedCaller) => void
   /** Ephemeral-target serial-queue delivery (M3) — see transport.EphemeralRouteDeps. */
   ephemeral?: EphemeralRouteDeps
+  /** LIVE-delivered topic → the target's `.topic` marker (fresh-vs-resume seam) —
+   *  see transport.RouteDeps.noteLiveTopic. Injected so the daemon never imports
+   *  lifecycle; the production main wires makeNoteLiveTopic. */
+  noteLiveTopic?: (identity: string, topic: string) => void
 }
 
 export async function callTool(
@@ -205,7 +209,7 @@ export async function callTool(
       attachments: Array.isArray(args.attachments) ? (args.attachments as string[]) : undefined,
     }
     const t0 = Date.now()
-    const sent = await routeSend(caller, input, { wake: deps.wake, ephemeral: deps.ephemeral })
+    const sent = await routeSend(caller, input, { wake: deps.wake, ephemeral: deps.ephemeral, noteLiveTopic: deps.noteLiveTopic })
     // Ф-#8a: ONE durable outcome line per delivery attempt (delivery.log, sibling
     // to lifecycle.log) — metadata only, never the body. Both branches of the
     // routeSend result are recorded, so a suspected loss is reconstructable from
@@ -367,6 +371,12 @@ export interface StartDaemonOptions extends StorageOptions {
    * lifecycle queue + drain (makeEphemeralRouteDeps).
    */
   ephemeral?: EphemeralRouteDeps
+  /**
+   * LIVE-delivered topic → the target identity's `.topic` marker (fresh-vs-resume
+   * seam) — see transport.RouteDeps.noteLiveTopic. OFF by default; the production
+   * main wires the lifecycle marker write (makeNoteLiveTopic).
+   */
+  noteLiveTopic?: (identity: string, topic: string) => void
   /**
    * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
    * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
@@ -399,6 +409,7 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
       deliveryLogDir: opts.deliveryLogDir,
       onDelivered: opts.onDelivered,
       ephemeral: opts.ephemeral,
+      noteLiveTopic: opts.noteLiveTopic,
     })
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
     res.on('close', () => {

package/src/daemon/main.test.ts

@@ -15,6 +15,7 @@ import {
   installDaemonPlist,
   makeArmEphemeralOnDelivered,
   makeEphemeralRouteDeps,
+  makeNoteLiveTopic,
   startConfiguredDaemon,
   DEFAULT_DAEMON_PORT,
 } from './main.ts'
@@ -23,6 +24,10 @@ import {
   ephemeralQueueDepth,
   hasEphemeralArmed,
   peekEphemeralTask,
+  readTopic,
+  resolveWakeMode,
+  setIdleReaped,
+  writeTopic,
   type LifecycleConfig,
 } from '../lifecycle/index.ts'
 import type { ResolvedCaller } from '../identity/index.ts'
@@ -304,3 +309,61 @@ describe('makeEphemeralRouteDeps (M3 serial-queue composition)', () => {
     expect(r.ok).toBe(false) // 'codex' is not declared for this worker
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// makeNoteLiveTopic — the live-delivered-topic composition (fresh-vs-resume seam):
+// the .topic marker must track the topic the session last WORKED ON, not the one
+// it woke with (defect 11.06: a day-stale wake-time marker false-freshed the
+// stop→start resume of a long-lived executor).
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('makeNoteLiveTopic (live-delivered topic → .topic marker)', () => {
+  function noteCfg(): LifecycleConfig {
+    const root = mkTmp()
+    return { stateDir: join(root, 'state'), eventLogDir: join(root, 'logs') } as LifecycleConfig
+  }
+
+  test('topic SHIFT → marker updated + ev=topic-note logged; same topic → no churn, no log spam', () => {
+    const cfg = noteCfg()
+    const note = makeNoteLiveTopic(cfg, {} as NodeJS.ProcessEnv)
+    writeTopic(cfg, 'claude-x', 'topic-a') // the wake established topic A
+    note('claude-x', 'topic-b') // a live delivery switches the work to B
+    expect(readTopic(cfg, 'claude-x')).toBe('topic-b')
+    const logPath = join(cfg.eventLogDir, 'lifecycle.log')
+    const log = readFileSync(logPath, 'utf8')
+    expect(log).toContain('ev=topic-note')
+    expect(log).toContain('identity=claude-x')
+    expect(log).toContain('topic=topic-b')
+    // the common case — every further message continues topic B → strictly nothing
+    note('claude-x', 'topic-b')
+    note('claude-x', 'topic-b')
+    expect(readFileSync(logPath, 'utf8').match(/ev=topic-note/g)?.length).toBe(1)
+  })
+
+  test('acceptance scenario (boris 11.06): woke with topic A → worked live-delivered topic B → clean stop-park → wake with topic B = RESUME, not fresh', () => {
+    const cfg = noteCfg()
+    const id = 'claude-x'
+    // executor peer cwd: no telegram interface (not human-conversational), no wake_policy
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(join(cwd, '.iapeer', 'peer-profile.json'), JSON.stringify({ personality: 'x', runtime: 'claude' }))
+    writeTopic(cfg, id, 'topic-a') // session woke with topic A (the stale pre-fix marker)
+    makeNoteLiveTopic(cfg)(id, 'topic-b') // ...then took topic-B messages in the LIVE session all day
+    setIdleReaped(cfg, id) // deliberate stop = clean park (stopPeer's promise)
+    const hasTranscript = () => ({ ok: true, ref: 'uuid-1' })
+    // pre-fix this read the stale 'topic-a' → cause=idle-reaped-new-topic → FRESH (context lost)
+    expect(resolveWakeMode(cfg, id, cwd, undefined, hasTranscript, 'topic-b')).toEqual({
+      resume: true,
+      resumeRef: 'uuid-1',
+      cause: 'idle-reaped-resume',
+    })
+  })
+
+  test('marker/log failure → no-op, never throws (a delivered message must stand)', () => {
+    const root = mkTmp()
+    const blocker = join(root, 'state-is-a-file')
+    writeFileSync(blocker, 'not a dir')
+    const cfg = { stateDir: join(blocker, 'state'), eventLogDir: join(blocker, 'logs') } as LifecycleConfig // mkdir must fail
+    expect(() => makeNoteLiveTopic(cfg)('claude-x', 'topic-b')).not.toThrow()
+  })
+})

package/src/daemon/main.ts

@@ -35,12 +35,15 @@ import {
   isEphemeralPeer,
   loadLifecycleConfig,
   processEagerRelaunches,
+  readTopic,
   resolveWakeRuntime,
   setEphemeralArmed,
   superviseTick,
   wakeOrSpawn,
+  writeTopic,
   type LifecycleConfig,
 } from '../lifecycle/index.ts'
+import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { buildProcessAddress } from '../core/socket.ts'
 import { err, ok } from '../core/errors.ts'
 import type { ResolvedCaller } from '../identity/index.ts'
@@ -98,6 +101,35 @@ export function makeArmEphemeralOnDelivered(cfg: LifecycleConfig): (caller: Reso
   }
 }
 
+/**
+ * The fourth lifecycle⇆transport seam (after makeWakeFn / makeArmEphemeralOnDelivered /
+ * makeEphemeralRouteDeps): record a LIVE-delivered topic as the target identity's
+ * `.topic` marker, so the marker tracks the topic the session LAST WORKED ON — the
+ * semantics resolveWakeMode's executor discriminator actually wants — not merely the
+ * topic it woke with. Live defect 11.06 (boris): an executor woke topicless at 13:13,
+ * worked a delivered topic all day, was stop-parked clean, and the topic-matching
+ * resume-wake at 17:06 compared against the STALE wake-time marker → cause=
+ * idle-reaped-new-topic → FRESH; the day's context was lost despite the clean park.
+ * Same-topic deliveries are a no-op (no marker churn, no log spam) — the lifecycle.log
+ * line `ev=topic-note` therefore marks exactly the moments the session's working
+ * topic SHIFTED, which is what a fresh-vs-resume postmortem needs. Best-effort: a
+ * marker/log failure never fails the already-delivered message.
+ */
+export function makeNoteLiveTopic(
+  cfg: LifecycleConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): (identity: string, topic: string) => void {
+  return (identity, topic) => {
+    try {
+      if (readTopic(cfg, identity) === topic) return
+      writeTopic(cfg, identity, topic)
+      appendLifecycleEvent(cfg.eventLogDir, { ev: 'topic-note', identity, topic }, { env })
+    } catch {
+      /* the marker is a discriminator hint — never fail a delivered message */
+    }
+  }
+}
+
 /**
  * wake_policy:"ephemeral" M3 — the serial-queue delivery composition (the third
  * lifecycle⇆transport seam after makeWakeFn / makeArmEphemeralOnDelivered).
@@ -178,6 +210,10 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     // M3 serial queue (see makeEphemeralRouteDeps): ephemeral TARGET ⇒ enqueue +
     // async drain. No-op for every other target.
     ephemeral: makeEphemeralRouteDeps(cfg, env),
+    // Live-delivered topic → the target's .topic marker (see makeNoteLiveTopic):
+    // the wake resolver's executor discriminator then compares against the topic
+    // the session last WORKED ON, not the one it woke with (defect 11.06).
+    noteLiveTopic: makeNoteLiveTopic(cfg, env),
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose

package/src/lifecycle/index.ts

@@ -223,8 +223,12 @@ export function clearStopped(cfg: LifecycleConfig, identity: string): void {
 //     Presence on a dead session = the daemon EAGERLY relaunches FRESH (does NOT
 //     wait for a message) and injects initial_prompt. Consumed on the relaunch.
 //   .deaths      : crash-loop guard — a small JSON ring of recent death epoch-ms.
-//   .topic       : the topic tag of the current/last session (executor fresh-vs-
-//     resume discriminator).
+//   .topic       : the topic the current/last session last WORKED ON (executor
+//     fresh-vs-resume discriminator). Written at wake (the boot topic) AND on
+//     every live delivery carrying a different non-empty topic (the daemon/CLI
+//     compositions wire transport's noteLiveTopic seam to writeTopic — defect
+//     11.06: a wake-only marker goes stale over a long session and false-freshes
+//     the stop→start resume the clean park promised).
 //   .ephemeral-armed : wake_policy:ephemeral M2 — set by the DAEMON when it routes
 //     an OUTBOUND send from an ephemeral worker (its single final reply, ADR-006:
 //     workers send no intermediate messages, so outbound ⇒ the task is answered).
@@ -381,7 +385,9 @@ export function readTopic(cfg: LifecycleConfig, identity: string): string {
   }
 }
 
-/** Store the incoming topic for the established session (raw string, best-effort). */
+/** Store the session's working topic (raw string, best-effort). Two writers: the
+ *  wake (boot topic, wakeOrSpawn) and live deliveries via the noteLiveTopic seam
+ *  (makeNoteLiveTopic) — so the marker follows the work, not just the boot. */
 export function writeTopic(cfg: LifecycleConfig, identity: string, topic: string): void {
   mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
   try {

package/src/transport/index.ts

@@ -440,6 +440,29 @@ export interface RouteDeps {
   wake?: WakeFn
   /** Ephemeral-target serial-queue delivery (M3); absent → normal routing. */
   ephemeral?: EphemeralRouteDeps
+  /** Fired after a successful LIVE delivery whose envelope carried a non-empty
+   *  topic — the hit path AND the post-wake fast-path redelivery, NOT the boot
+   *  first-message (the wake itself records its topic). The fresh-vs-resume seam:
+   *  lifecycle keeps a per-identity `.topic` marker the wake resolver compares
+   *  the incoming topic against; before this hook the marker was written ONLY at
+   *  wake, so it held «the topic the session woke with», while the resolver's
+   *  semantics want «the topic the session last worked on». A long-lived executor
+   *  that took live-delivered messages of topic B all day then false-FRESHED on
+   *  stop→start→wake with topic B (live incident 11.06, claude-iapeer: a day of
+   *  context lost to cause=idle-reaped-new-topic). Injected so transport never
+   *  imports lifecycle (layering — main.ts is where the two meet); call sites
+   *  swallow hook errors (a hook must never fail a delivered message). */
+  noteLiveTopic?: (identity: string, topic: string) => void
+}
+
+/** Best-effort noteLiveTopic invocation — only on a non-empty topic, never throws. */
+function noteTopic(deps: RouteDeps, identity: string, topic: string | undefined): void {
+  if (!topic) return
+  try {
+    deps.noteLiveTopic?.(identity, topic)
+  } catch {
+    /* a post-delivery hook must never fail the delivery */
+  }
 }
 
 function truncateTopic(raw: string | undefined): string | undefined {
@@ -534,6 +557,7 @@ export async function routeSend(
     // peer.cwd enables the Ф-B transcript-mtime liveness probe (busy-session case).
     const delivered = deliverViaTmux(target.value, envelope, peer.cwd)
     if (!delivered.ok) return delivered
+    noteTopic(deps, target.value.address, topic)
     return ok({
       ok: true,
       delivered_to: { personality: target.value.personality, runtime: target.value.runtime },
@@ -567,6 +591,7 @@ export async function routeSend(
   if (woke.taskDelivered === false) {
     const delivered = deliverViaTmux(live.value, envelope, peer.cwd)
     if (!delivered.ok) return delivered
+    noteTopic(deps, live.value.address, topic)
     return ok({
       ok: true,
       delivered_to: { personality: live.value.personality, runtime: live.value.runtime },

package/src/transport/routesend-wake.test.ts

@@ -137,3 +137,72 @@ describe('routeSend wake fast-path (concurrent-sender envelope loss)', () => {
     expect(r.error.message).toMatch(/verify-before-act|not live/)
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// noteLiveTopic seam — a LIVE delivery carrying a topic must surface it to the
+// injected hook (lifecycle's .topic marker write), so the fresh-vs-resume
+// discriminator compares against the topic the session last WORKED ON, not the
+// one it woke with (defect 11.06: stale wake-time marker → false fresh).
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('routeSend noteLiveTopic seam (live-delivered topic)', () => {
+  test('live hit with a topic → hook fired ONCE with the TARGET identity + topic', async () => {
+    startTargetSession()
+    const notes: Array<[string, string]> = []
+    const r = await routeSend(
+      caller,
+      { personality: TARGET, message: 'm', topic: 'fix-resume' },
+      { noteLiveTopic: (id, t) => notes.push([id, t]) },
+    )
+    expect(r.ok).toBe(true)
+    expect(notes).toEqual([[`telegram-${TARGET}`, 'fix-resume']])
+    killTargetSession()
+  })
+
+  test('no topic → hook NOT fired; a throwing hook never fails the delivered message', async () => {
+    startTargetSession()
+    const notes: string[] = []
+    const r1 = await routeSend(caller, { personality: TARGET, message: 'm1' }, { noteLiveTopic: () => { notes.push('x') } })
+    expect(r1.ok).toBe(true)
+    expect(notes).toEqual([])
+    const r2 = await routeSend(
+      caller,
+      { personality: TARGET, message: 'm2', topic: 't' },
+      { noteLiveTopic: () => { throw new Error('boom') } },
+    )
+    expect(r2.ok).toBe(true)
+    killTargetSession()
+  })
+
+  test('post-wake fast-path redelivery (taskDelivered:false) also notes the topic — it is a LIVE delivery', async () => {
+    const notes: Array<[string, string]> = []
+    const wake: WakeFn = async () => {
+      startTargetSession()
+      return { status: 'READY', woke: false, runtime: 'telegram', taskDelivered: false }
+    }
+    const r = await routeSend(
+      caller,
+      { personality: TARGET, message: 'm', topic: 'tt' },
+      { wake, noteLiveTopic: (id, t) => notes.push([id, t]) },
+    )
+    expect(r.ok).toBe(true)
+    expect(notes).toEqual([[`telegram-${TARGET}`, 'tt']])
+    killTargetSession()
+  })
+
+  test('boot first-message delivery (woke:true) does NOT fire the hook — the wake records its own topic', async () => {
+    const notes: string[] = []
+    const wake: WakeFn = async () => {
+      startTargetSession()
+      return { status: 'READY', woke: true, runtime: 'telegram', taskDelivered: true }
+    }
+    const r = await routeSend(
+      caller,
+      { personality: TARGET, message: 'm', topic: 'tb' },
+      { wake, noteLiveTopic: () => { notes.push('x') } },
+    )
+    expect(r.ok).toBe(true)
+    expect(notes).toEqual([])
+    killTargetSession()
+  })
+})