@agfpd/iapeer 0.4.23 → 0.4.25

package/CHANGELOG.md

@@ -10,6 +10,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.25] - 2026-06-22
+
+### Fixed
+
+- **`connect telegram` now eager-reindexes the registry** (#1). `interface bot` merges
+  interfaces.telegram into the per-cwd profile (source of truth), but the derived registry
+  (peers-profiles.json) is a projection that only refreshed on specific verbs — so until
+  then the peer's telegram FACE was invisible to the sender-guard (`hasTelegramPresence`
+  reads the REGISTRY passport), **blocking the peer's outbound telegram** (observed live:
+  impact-finder "no telegram face"). connect now calls `reindexFromLocals` after a
+  successful `interface bot` (best-effort), so the face lands in the registry immediately —
+  no manual `iapeer verify --fix`.
+- **Launchd-revive delivery retry** (#2): a MISS on a launchd-managed target — which the
+  daemon can't wake (H4) but launchd KeepAlive revives in ~1s — no longer fails terminally
+  in ~16ms. During a router restart (on `connect` / `iapeer update`) an in-flight delivery
+  was lost (observed: `natalya→arthur ok=false ms=16` mid-restart — a message to a HUMAN).
+  routeSend now retries-resolve for a bounded window (`IAP_LAUNCHD_REVIVE_GRACE_MS`, ~4s)
+  and delivers the instant the target revives; it re-resolves each poll (verify-before-act,
+  so the ok reflects a CONFIRMED delivery — no false-OK), and a genuinely-down peer still
+  fails LOUD and retryable (never silent). `isLaunchdManaged` injected via deps (no
+  transport→lifecycle coupling).
+
+## [0.4.24] - 2026-06-22
+
+### Fixed
+
+- **`iapeer connect telegram <peer>` (and the `enable telegram` alias) no longer fails for a
+  peer whose personality isn't a valid Telegram @username** (e.g. a hyphen: "impact-finder").
+  connect passed the PERSONALITY as the bot @username to telegram-runtime (which keys bots by
+  `<bot-username>`), so a hyphenated personality was rejected ("must be a telegram @username").
+  The bot @username is TOKEN-derived (set in @BotFather), never the personality. connect now
+  resolves it from the token via Telegram **getMe** and uses that for `bot add` / `interface
+  bot` / storage; the human still owes only the token. An invalid/unreachable token fails
+  early with a getMe-rejected message. (The getMe lives in the telegram-glue module
+  `connect/index.ts` — the foundation core stays Telegram-API-free.)
+
 ## [0.4.23] - 2026-06-22
 
 ### Added
@@ -352,7 +388,9 @@ Initial public release — the foundation core of the iapeer multi-agent ecosyst
 - **Heterogeneous peers** — AI agents (Claude, Codex), humans (Telegram), and services
   (timer = cron, watcher = event) are all first-class and addressed the same way.
 
-[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.23...HEAD
+[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.25...HEAD
+[0.4.25]: https://github.com/agfpd/iapeer/compare/v0.4.24...v0.4.25
+[0.4.24]: https://github.com/agfpd/iapeer/compare/v0.4.23...v0.4.24
 [0.4.23]: https://github.com/agfpd/iapeer/compare/v0.4.22...v0.4.23
 [0.4.22]: https://github.com/agfpd/iapeer/compare/v0.4.21...v0.4.22
 [0.4.21]: https://github.com/agfpd/iapeer/compare/v0.4.20...v0.4.21

package/package.json

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

package/src/connect/index.ts

@@ -5,9 +5,11 @@
 //
 // The human owes EXACTLY ONE external fact: the bot token (prompt walks them
 // through @BotFather → /newbot). Everything else the system resolves: the bot
-// alias (= the peer's personality), `telegram-runtime bot add` (owner adds getMe
-// validation — an invalid token fails THERE, early), `telegram-runtime interface
-// bot` (profile merge; precondition: the peer is registered), then the MANDATORY
+// @username via Telegram getMe(token) — the bot key is TOKEN-derived, NOT the peer
+// personality (a personality may contain a hyphen, structurally invalid as a
+// @username; telegram-runtime keys bots by <bot-username>), `telegram-runtime bot add`
+// (also validates the token), `telegram-runtime interface bot` (profile merge;
+// precondition: the peer is registered), then the MANDATORY
 // router-session restart (the live poller reads bots/ ONCE at start, no fs-watch —
 // without the restart the channel is dead both ways), and the activation hint:
 // the FIRST message from the human to the bot opens the chat (a Telegram platform
@@ -23,6 +25,7 @@ import { spawnSync } from 'child_process'
 import { normalizeIntelligenceValue } from '../core/constants.ts'
 import { runtimeRoot } from '../storage/index.ts'
 import { findPeer, readPeersIndex } from '../registry/index.ts'
+import { reindexFromLocals } from '../identity/profileStandard.ts'
 import { readRuntimeManifest } from '../runtime/index.ts'
 
 export interface TgRunResult {
@@ -51,6 +54,9 @@ export interface ConnectTelegramOptions {
   runTg?: TgRunner
   /** Injectable router restart (tests). Default: stopPeer→startPeer strictly in order. */
   restart?: RestartFn
+  /** Injectable bot-@username resolver (tests). Default: Telegram getMe(token). Returns the
+   *  bare @username (no leading @) or null on a rejected/unreachable token. */
+  resolveUsername?: (token: string) => Promise<string | null>
 }
 
 export interface ConnectTelegramResult {
@@ -60,6 +66,7 @@ export interface ConnectTelegramResult {
     | 'refused-no-token' // non-tty and no --token (or an empty tty answer)
     | 'unregistered-peer' // precondition: the peer must be in the registry
     | 'runtime-missing' // no telegram runtime manifest — install it first
+    | 'bad-token' // Telegram getMe rejected the token (invalid/revoked) or was unreachable
     | 'bot-add-failed' // telegram-runtime bot add exited non-zero (incl. getMe refusal)
     | 'interface-failed' // telegram-runtime interface bot exited non-zero
   peer: string
@@ -93,6 +100,26 @@ function readBotEnv(alias: string, env: NodeJS.ProcessEnv): string | null {
   }
 }
 
+/**
+ * Resolve the bot's REAL @username from the token via Telegram getMe — the bot identity
+ * is TOKEN-derived (BotFather sets it), NOT the peer personality. telegram-runtime keys
+ * bots by `<bot-username>` (`bot add <bot-username>`, `interface bot <bot-username>`), and a
+ * personality can contain a hyphen which is structurally invalid as a @username — so the
+ * personality can NEVER be the bot-username. Returns the bare username (no leading @) or
+ * null on a rejected/unreachable token. The token goes literally in the URL path
+ * (Telegram tokens are `<digits>:<urlsafe>`; no encoding).
+ */
+async function defaultResolveBotUsername(token: string): Promise<string | null> {
+  try {
+    const r = await fetch(`https://api.telegram.org/bot${token}/getMe`)
+    const j = (await r.json()) as { ok?: boolean; result?: { username?: unknown } }
+    const u = j?.ok === true && typeof j.result?.username === 'string' ? j.result.username.trim().replace(/^@/, '') : ''
+    return u || null
+  } catch {
+    return null // network error / non-JSON → treat as unresolvable (bad-token)
+  }
+}
+
 /** Resolve the telegram-runtime CLI bin from the manifest's selfConfig command (the
  *  package's own absolute bin — PATH-independent, launchd-safe). */
 function resolveTgBin(env: NodeJS.ProcessEnv): string | null {
@@ -173,8 +200,17 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
     if (!token) return { state: 'refused-no-token', peer, detail: 'no answer — nothing connected' }
   }
 
+  // Resolve the bot's REAL @username from the token (getMe) — NOT the personality. The
+  // bot-username is token-derived; a personality with a hyphen (e.g. "impact-finder") is
+  // structurally invalid as a @username and telegram-runtime (which keys bots by
+  // <bot-username>) rejects it. getMe also validates the token early (bad token → fail here).
+  const resolveUsername = opts.resolveUsername ?? defaultResolveBotUsername
+  const botUsername = await resolveUsername(token)
+  if (!botUsername) {
+    return { state: 'bad-token', peer, detail: 'Telegram getMe rejected the token (invalid/revoked) or was unreachable — recheck the token with @BotFather' }
+  }
   const runTg = opts.runTg ?? defaultRunTg(tgBin)
-  const alias = peer // bot alias = the peer's personality (design §(в); passes the owner's NAME_RE)
+  const alias = botUsername // bot key = the REAL @username from getMe (telegram-runtime keys bots by <bot-username>)
   const before = readBotEnv(alias, env)
 
   // (1) bot add — token → bots/<alias>/.env. Owner adds getMe validation here: an
@@ -183,17 +219,10 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
   if (add.status !== 0) {
     return { state: 'bot-add-failed', peer, detail: (add.stderr || add.stdout || `exit ${add.status}`).trim() }
   }
-  // @username: the bots/<alias>/.env TELEGRAM_BOT_USERNAME field is the RELIABLE
-  // source (present on the live host; survives a quiet bot-add stdout — acceptance
-  // testing saw the activation line degrade to the BotFather hint). stdout
-  // match stays as the fallback.
-  const envAfterAdd = readBotEnv(alias, env)
-  const envUser = envAfterAdd?.match(/^TELEGRAM_BOT_USERNAME=(.+)$/m)?.[1]?.trim()
-  const username = envUser
-    ? envUser.startsWith('@')
-      ? envUser
-      : `@${envUser}`
-    : add.stdout.match(/@[A-Za-z0-9_]{3,}/)?.[0]
+  // @username for display / the activation hint: the bot key (alias) IS the
+  // getMe-resolved username, so the display form is simply `@<alias>` — no need to
+  // re-parse bots/<alias>/.env (telegram-runtime writes the same value there).
+  const username = `@${alias}`
 
   // (2) interface bot — merge the channel binding into the peer's profile.
   const iface = runTg(['interface', 'bot', alias, '--peer', peer], env)
@@ -201,6 +230,22 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
     return { state: 'interface-failed', peer, username, detail: (iface.stderr || iface.stdout || `exit ${iface.status}`).trim() }
   }
 
+  // (2b) EAGER reindex — `interface bot` merged interfaces.telegram into the per-cwd
+  // profile (source of truth), but the derived registry (peers-profiles.json) is a
+  // PROJECTION that only refreshes on specific verbs (verify --fix, default-runtime…).
+  // Until then the peer's telegram FACE is INVISIBLE to the sender-guard
+  // (hasTelegramPresence reads the REGISTRY passport) — so the peer's OUTBOUND telegram
+  // is blocked ("no telegram face") + list/attach are stale. Project it now (same
+  // reindexFromLocals the default-runtime verb uses). Best-effort: a reindex hiccup must
+  // not fail a connect whose profile + bot are already in place (registry catches up on
+  // the next reindex verb). Runs on EVERY connect, incl. the idempotent no-op below — so
+  // a registry that drifted on a prior (pre-fix) connect self-heals here too.
+  try {
+    await reindexFromLocals({ env })
+  } catch {
+    /* registry lazily catches up on the next reindex verb; profile + bot are correct */
+  }
+
   // (3) Idempotency gate: the SAME token leaves bots/<alias>/.env byte-stable →
   // the live poller already loaded these credentials → NO restart, clean no-op.
   const after = readBotEnv(alias, env)

package/src/daemon/index.ts

@@ -194,6 +194,10 @@ export interface CallToolDeps {
   noteLiveTopic?: (identity: string, topic: string) => void
   /** Busy-human-composer queue — see transport.createComposerDeliveryQueue. */
   composerQueue?: ComposerQueueRouteDeps
+  /** H4 launchd-managed detector — see transport.RouteDeps.isLaunchdManaged (the
+   *  launchd-revive delivery retry). Injected so the daemon never imports lifecycle;
+   *  the production main wires the real isLaunchdManaged. */
+  isLaunchdManaged?: (personality: string) => boolean
 }
 
 export async function callTool(
@@ -216,6 +220,7 @@ export async function callTool(
       ephemeral: deps.ephemeral,
       noteLiveTopic: deps.noteLiveTopic,
       composerQueue: deps.composerQueue,
+      isLaunchdManaged: deps.isLaunchdManaged,
     })
     // Ф-#8a: ONE durable outcome line per delivery attempt (delivery.log, sibling
     // to lifecycle.log) — metadata only, never the body. Both branches of the
@@ -392,6 +397,9 @@ export interface StartDaemonOptions extends StorageOptions {
    * senders on shutdown/restart.
    */
   composerQueue?: ComposerQueueRouteDeps
+  /** H4 launchd-managed detector — see CallToolDeps.isLaunchdManaged / the launchd-revive
+   *  delivery retry. OFF by default (library/tests); production main wires the real one. */
+  isLaunchdManaged?: (personality: string) => boolean
   /**
    * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
    * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
@@ -426,6 +434,7 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
       ephemeral: opts.ephemeral,
       noteLiveTopic: opts.noteLiveTopic,
       composerQueue: opts.composerQueue,
+      isLaunchdManaged: opts.isLaunchdManaged,
     })
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
     res.on('close', () => {

package/src/daemon/main.ts

@@ -35,6 +35,7 @@ import {
   drainEphemeralQueue,
   enqueueEphemeralTask,
   isEphemeralPeer,
+  isLaunchdManaged,
   addTopic,
   loadLifecycleConfig,
   processEagerRelaunches,
@@ -332,6 +333,10 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     // Busy-human-composer queue: fast queued ack, async drain, fail all pending
     // on daemon close/update so a queued envelope is never silently lost.
     composerQueue,
+    // H4 launchd-revive delivery retry (see RouteDeps.isLaunchdManaged): a MISS on a
+    // launchd-managed target (the daemon can't wake it, but KeepAlive revives it) → retry-
+    // resolve for a bounded window instead of failing in ~16ms — bridges a router restart.
+    isLaunchdManaged: (personality: string) => isLaunchdManaged(personality, 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/transport/index.ts

@@ -176,6 +176,17 @@ function hostLivenessGraceMs(): number {
   return Number.isFinite(n) && n >= 0 ? n : livenessGraceMs()
 }
 
+// Launchd-revive retry — a MISS on a launchd-managed target the daemon can't wake (H4)
+// but launchd KeepAlive WILL revive (router restart / crash-revive window). routeSend
+// re-resolves for up to this window before failing, bridging the gap (silent-loss guard).
+// Env-tunable; default ~4s (a bootout→bootstrap router restart settles well under it).
+const LAUNCHD_REVIVE_POLL_MS = 300
+function launchdReviveGraceMs(): number {
+  const raw = process.env.IAP_LAUNCHD_REVIVE_GRACE_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 4000
+}
+
 // ─── Warm delivery (pty-only — supervisor socket) ────────────────────────────────────────────────
 
 /** Test seam for `deliverWarm`. Production defaults route on the real supervisor; tests inject a
@@ -793,6 +804,17 @@ export interface RouteDeps {
    *  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
+  /** H4 launchd-managed detector (injected so transport never imports lifecycle —
+   *  main.ts wires the real `isLaunchdManaged`). A MISS on a launchd-managed target is
+   *  almost always a TRANSIENT restart window (router restart on connect / `iapeer
+   *  update`, or a crash that KeepAlive is reviving), NOT a real outage: the daemon
+   *  can't wake it (H4) but launchd WILL revive it in ~1s. So routeSend retries the
+   *  RESOLVE for a bounded window before failing, bridging the gap (prevents the
+   *  silent-loss class: an in-flight delivery — esp. to a HUMAN over a telegram router —
+   *  dropped during a restart). Absent → no retry (legacy behaviour). */
+  isLaunchdManaged?: (personality: string) => boolean
+  /** Injectable async sleep for the launchd-revive retry poll (tests). Default: setTimeout. */
+  sleep?: (ms: number) => Promise<void>
 }
 
 /** Best-effort noteLiveTopic invocation — only on a non-empty topic, never throws. */
@@ -1159,6 +1181,42 @@ export async function routeSend(
 
   // MISS — peer offline.
   if (!deps.wake) return target // Ф1: explicit offline, no wake
+  // LAUNCHD-REVIVE RETRY: a launchd-managed target the daemon can't wake (H4) but launchd
+  // KeepAlive WILL revive — a MISS here is almost always a transient RESTART WINDOW (router
+  // restart on connect / `iapeer update`, or a crash-revive), not a real outage. Wake would
+  // just refuse (launchd-managed) and the delivery would fail in ~16ms — losing an in-flight
+  // message (observed: natalya→arthur ok=false ms=16 during a connect router restart; a
+  // message to a HUMAN, the silent-loss-adjacent class). Bridge it: re-resolve for a bounded
+  // window and deliver the instant it revives. Each poll RE-RESOLVES the live target
+  // (verify-before-act) → the ok reflects a CONFIRMED delivery (no false-OK); a genuinely
+  // down peer still fails LOUD after the window (retryable, never silent).
+  if (deps.isLaunchdManaged?.(personality)) {
+    const sleep = deps.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)))
+    const reviveDeadline = monotonicMs() + launchdReviveGraceMs()
+    while (monotonicMs() < reviveDeadline) {
+      await sleep(LAUNCHD_REVIVE_POLL_MS)
+      const revived = resolvePeerDeliveryTarget(personality, runtime, peer)
+      if (!revived.ok) continue // not back yet — keep polling until the deadline
+      if (revived.value.address === caller.address) return err('cannot send to self')
+      const reviveGuard = telegramSenderGuard(caller, revived.value.runtime, personality)
+      if (!reviveGuard.ok) return reviveGuard
+      const delivered = await deliverWarm(revived.value, envelope, peer.cwd)
+      if (delivered.ok) {
+        noteTopic(deps, revived.value.address, topic)
+        return ok({
+          ok: true,
+          delivered_to: { personality: revived.value.personality, runtime: revived.value.runtime },
+          woke: false,
+          ts: new Date().toISOString(),
+        })
+      }
+      // resolved but the deliver didn't land (session still settling) → keep polling
+    }
+    return err(
+      `peer "${personality}" (launchd-managed) offline and did not revive within ${launchdReviveGraceMs()}ms ` +
+        `(restart window outlasted the grace?) — message NOT delivered; retry`,
+    )
+  }
   const woke = await deps.wake({ personality, runtime, topic, task: envelope })
   if (woke.status === 'FAILED') {
     // C1 — a durably STOPPED peer is a deliberate halt, not a transient miss: