@agfpd/iapeer 0.4.28 → 0.4.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.28",
+  "version": "0.4.30",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -1291,6 +1291,32 @@ export function renderUsage(width: number = helpWidth()): string {
   return lines.join('\n') + '\n'
 }
 
+/** Focused help for ONE verb: the VERBS entry whose signature's first token equals `verb`,
+ *  rendered as its own `usage: iapeer <sig>` + wrapped description — or null when `verb` is
+ *  not a known verb (the caller then falls back to the full renderUsage). This is why
+ *  `iapeer connect telegram --help` prints connect's OWN usage instead of the whole verb list
+ *  (the prior behavior: `--help` anywhere dumped the general usage, burying the subcommand the
+ *  user asked about). First-token match is unambiguous — no two VERBS share a leading token. */
+export function renderVerbHelp(verb: string, width: number = helpWidth()): string | null {
+  const entry = VERBS.find(v => v.sig.split(/\s+/)[0] === verb)
+  if (!entry) return null
+  const W = Math.max(40, width)
+  const lines = [`usage: iapeer ${entry.sig}`, ...wrapText(entry.desc, W - 2).map(d => `  ${d}`)]
+  return lines.join('\n') + '\n'
+}
+
+/** Which verb's help an explicit help request targets, or null for the GENERAL usage:
+ *   - `<verb> --help` / `<verb> -h`  → the verb (argv[0], when it is not itself a help token)
+ *   - `help <verb>`                  → argv[1]
+ *   - bare `help` / `--help` / `-h`  → null (whole verb list)
+ *  An unknown target falls through to the general usage via renderVerbHelp returning null. */
+export function helpTargetVerb(argv: string[]): string | null {
+  const first = argv[0]
+  if (first && first !== 'help' && first !== '--help' && first !== '-h') return first
+  if (first === 'help' && argv[1]) return argv[1]!
+  return null
+}
+
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
   const [verb, ...rest] = argv
   // CLI hygiene (design «Onboard костяка» §CLI-гигиена): an explicit help request —
@@ -1301,7 +1327,10 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
   // match is safe: the look-ahead parser never consumes a `--`-token as a value, so
   // a LITERAL "--help" value is only expressible as `--key=--help` (not intercepted).
   if (verb === 'help' || argv.includes('--help') || argv.includes('-h')) {
-    process.stdout.write(renderUsage())
+    // Per-verb help when a known verb is named (`connect telegram --help` → connect's own usage,
+    // `help connect` → same); the general verb list only for a bare/unknown help request.
+    const target = helpTargetVerb(argv)
+    process.stdout.write((target && renderVerbHelp(target)) || renderUsage())
     return 0
   }
   const { positionals, flags } = parseArgs(rest)

package/src/init/index.ts

@@ -9,7 +9,7 @@
 // persistent-peer install-gate class is gone). A cold-start claude session
 // (--dangerously-skip-permissions, as the launch primitive runs it) finds the
 // `.mcp.json` http server and send_to_peer is callable on its FIRST turn. The server's
-// project-approval is pre-granted by ensureClaudeProjectMcpEnabled (the
+// project-approval is pre-granted by ensureClaudeProjectSettings (the
 // enableAllProjectMcpServers flag below); on a VIRGIN config without it the launch's
 // bootDialogKeys clears the one-time "new MCP servers found" dialog as a backstop.
 //
@@ -121,27 +121,33 @@ export function writeClaudeMcpConfig(cwd: string, personality: string, daemonUrl
 }
 
 /**
- * Idempotently enable project-scope MCP servers for a claude peer by merging
- * `"enableAllProjectMcpServers": true` into `<cwd>/.claude/settings.json`.
+ * Idempotently merge the project-LOCAL claude settings that pre-empt BLOCKING startup/
+ * mid-session modals for a headless peer, into `<cwd>/.claude/settings.json`:
+ *
+ *   - `"enableAllProjectMcpServers": true` — on a VIRGIN claude config, the FIRST launch
+ *     in a cwd carrying a `.mcp.json` (writeClaudeMcpConfig above) shows a BLOCKING "N new
+ *     MCP servers found in this project" approval dialog BEFORE the input prompt; a headless
+ *     peer has no one to approve it, so the wake stalls. This flag pre-approves the cwd's MCP
+ *     servers so the dialog never appears (verified live, claude 2.1.183). Set unconditionally.
+ *   - `"tui": "default"` — pins the CLASSIC renderer so claude never pops its one-time
+ *     "Try the new fullscreen renderer?" upsell modal (a BLOCKING mid-session nag that froze
+ *     live fleet peers; empirically an explicit tui choice suppresses it — verified live). This
+ *     is the PREVENTION belt to the supervisor nag-watcher: init keeps the modal from appearing
+ *     for a new peer at all, the watcher dismisses the class on every peer mid-session. Set ONLY
+ *     when ABSENT — never override an explicit operator/peer tui choice already in the file.
  *
- * Why: on a VIRGIN claude config, the FIRST launch in a cwd carrying a `.mcp.json`
- * (writeClaudeMcpConfig above) shows a BLOCKING "N new MCP servers found in this
- * project" approval dialog BEFORE the input prompt — a headless peer has no one to
- * approve it, so the wake stalls. This project-LOCAL flag pre-approves the cwd's MCP
- * servers so the dialog never appears (verified live, claude 2.1.183). It is
  * PROJECT-scoped (this peer's cwd only) — it does NOT touch the user's GLOBAL
- * ~/.claude/settings.json, so it never alters the user's own claude environment (the
- * same constraint that forbids a global skipDangerousModePermissionPrompt). The launch
- * adapter's bootDialogKeys also Enter-confirms this dialog as a belt-and-suspenders
- * backstop, so a peer whose cwd predates this flag still boots.
+ * ~/.claude/settings.json, so it never alters the user's own claude environment (the same
+ * constraint that forbids a global skipDangerousModePermissionPrompt). Both modals also have
+ * runtime backstops (bootDialogKeys Enter-confirms the MCP dialog; the supervisor nag-watcher
+ * declines the fullscreen modal), so a peer whose cwd predates these keys still boots safely.
  *
- * NO-CLOBBER merge (the file may carry foreign blocks — plugin enables, statusline
- * wrappers, the native-memory lever): parse/patch + atomic write; a non-object
- * settings.json is REFUSED rather than overwritten. Returns the written path, or null
- * when already set / on a refusal / on any error (best-effort, never throws — the
- * bootDialogKeys backstop covers the dialog regardless).
+ * NO-CLOBBER merge (the file may carry foreign blocks — plugin enables, statusline wrappers,
+ * the native-memory lever): parse/patch + atomic write; a non-object settings.json is REFUSED
+ * rather than overwritten. Returns the written path, or null when nothing changed / on a refusal
+ * / on any error (best-effort, never throws — the runtime backstops cover the modals regardless).
  */
-export function ensureClaudeProjectMcpEnabled(cwd: string): string | null {
+export function ensureClaudeProjectSettings(cwd: string): string | null {
   const path = claudeSettingsPath(cwd)
   try {
     let obj: Record<string, unknown> = {}
@@ -150,13 +156,21 @@ export function ensureClaudeProjectMcpEnabled(cwd: string): string | null {
       if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null // refuse to clobber a non-object
       obj = raw as Record<string, unknown>
     }
-    if (obj.enableAllProjectMcpServers === true) return path // already enabled
-    obj.enableAllProjectMcpServers = true
+    let changed = false
+    if (obj.enableAllProjectMcpServers !== true) {
+      obj.enableAllProjectMcpServers = true // pre-approve the cwd's MCP servers (no boot approval dialog)
+      changed = true
+    }
+    if (obj.tui === undefined) {
+      obj.tui = 'default' // classic renderer → no fullscreen-upsell modal; ABSENT-only (no override of an explicit choice)
+      changed = true
+    }
+    if (!changed) return path // both already in place — idempotent, no rewrite
     mkdirSync(dirname(path), { recursive: true })
     writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`, 0o644)
     return path
   } catch {
-    return null // best-effort; the bootDialogKeys backstop still clears the dialog
+    return null // best-effort; the bootDialogKeys / nag-watcher backstops still clear the modals
   }
 }
 
@@ -476,7 +490,7 @@ export async function initPeer(opts: InitPeerOptions): Promise<InitPeerResult> {
     // Pre-approve the cwd's project MCP servers so the FIRST virgin-config launch does
     // not stall on the blocking "N new MCP servers found" dialog (project-local, never
     // touches the user's global settings; bootDialogKeys is the backstop).
-    ensureClaudeProjectMcpEnabled(provisioned.cwd)
+    ensureClaudeProjectSettings(provisioned.cwd)
   }
   // codex: write the token-free host-wide config.toml block (dummy bearer flips codex's
   // auth gate; the OPEN daemon authenticates by the identity header). send_to_peer works

package/src/launch/adapters/claude.ts

@@ -136,6 +136,11 @@ export const claudeAdapter: RuntimeAdapter = {
     ghostTextSgr: ['2', '38;5;246'],
   },
 
+  // claude logs an accepted paste PROMPTLY (sub-second: a queue-operation when busy,
+  // the user-turn when idle), so the message-specific transcript confirm is both cheap
+  // and a swallow-guard (the false-OK class). Keep it. (See RuntimeAdapter.deliveryConfirm.)
+  deliveryConfirm: 'transcript',
+
   /**
    * argv = claudeBin + headless flags + (system-prompt-file when set) +
    * (--continue when resuming) + extraArgs.

package/src/launch/adapters/codex.ts

@@ -177,6 +177,16 @@ export const codexAdapter: RuntimeAdapter = {
     ghostTextSgr: ['2', '38;5;246'],
   },
 
+  // codex writes NO prompt-acceptance record — its session-jsonl user-input appears only
+  // when the model TURN ingests the message (during a long turn, tens of seconds away;
+  // measured ~80s live 2026-06-25). But its input queue is DURABLE: a mid-turn submit is
+  // held and processed at the next turn boundary, never lost (verified live — an 80s turn
+  // still ingested + replied with the exact probe token, despite the send false-FAILing at
+  // the 8s grace). So the flushed socket-ack IS the delivery confirm; a transcript grace
+  // only false-FAILs a message that WILL be processed → wrong fallback escalation. A
+  // genuinely dead session still fails at the socket-ack. (See RuntimeAdapter.deliveryConfirm.)
+  deliveryConfirm: 'socket-ack',
+
   /**
    * argv = codexBin + (resume --last when spec.resume) + the TUI args +
    * (doctrine via -c when systemPromptFile set) + bypass + extraArgs. Order is

package/src/launch/types.ts

@@ -235,6 +235,32 @@ export interface RuntimeAdapter {
    */
   deliveryMarkers: DeliveryMarkers
 
+  /**
+   * How a delivered envelope's LANDING is confirmed AFTER the socket-ack, in
+   * deliverViaHost (transport). Owned by the adapter because it is a property of
+   * HOW the runtime logs an accepted message, not transport policy. A router
+   * (kind:'router') is always socket-ack by structure and short-circuits before
+   * this field is read; it refines the TUI runtimes. Absent → 'transcript' (the
+   * strict default: a new/unknown runtime gets the swallow-guarding confirm, never
+   * a weaker one).
+   *   - 'transcript' (claude): the runtime writes an acceptance record CARRYING the
+   *     envelope PROMPTLY — sub-second: a queue-operation when busy, the user-turn
+   *     when idle. So a message-specific transcript-carries-envelope check within a
+   *     short grace BOTH proves landing AND catches a paste swallowed at a turn
+   *     boundary (the false-OK class, incident 2026-06-23). Cheap and safe → keep it.
+   *   - 'socket-ack' (codex): the runtime writes NO acceptance record — its
+   *     session-jsonl user-input appears only when the model TURN INGESTS the
+   *     message, which during a long turn is many tens of seconds away (measured ~80s
+   *     live, 2026-06-25). But its input queue is DURABLE: a mid-turn submit is HELD
+   *     and processed at the next turn boundary, never lost (verified live — an 80s
+   *     turn still ingested + replied with the exact probe token). So the flushed
+   *     socket-ack (bytes left us AND drained to the pty) IS the delivery confirm; a
+   *     transcript grace here only ever FALSE-FAILs a message that WILL be processed,
+   *     wrongly escalating to a fallback peer. A genuinely dead session still fails
+   *     at the socket-ack (no socket / stalled flush) → really-dead still escalates.
+   */
+  deliveryConfirm?: 'transcript' | 'socket-ack'
+
   /**
    * If set, launch REFUSES unless the peer's intelligence equals this value
    * (fail-loud). telegram → 'natural' — it is a human channel; launching an

package/src/transport/index.ts

@@ -157,20 +157,19 @@ export function resolvePeerDeliveryTarget(
 const LIVENESS_POLL_MS = 100
 
 // Confirm grace — how long deliverViaHost polls for a transcript record CARRYING our envelope before
-// declaring a false-FAIL. Per-RUNTIME because the runtimes log an accepted injection at different
-// times: claude writes the queue-operation (busy) / user-turn (idle) record PROMPTLY (sub-second), so
-// a short grace suffices; codex writes its session-jsonl user-input only at model-turn-START (TTFT
-// measured ~4-6s after submit), so it needs a longer window or every codex delivery would false-FAIL
-// before the first write. `IAP_HOST_LIVENESS_GRACE_MS` overrides BOTH (operator calibration; tests set
-// 0 for an immediate deterministic fail). Prefer a false-FAIL (sender retries) over a false-OK (silent
-// loss, which the contract forbids).
-const CONFIRM_GRACE_CLAUDE_MS = 4000
-const CONFIRM_GRACE_CODEX_MS = 8000
-function confirmGraceMs(runtime: string): number {
+// declaring a false-FAIL. This applies ONLY to the 'transcript'-confirm runtimes (claude): claude
+// writes the queue-operation (busy) / user-turn (idle) record PROMPTLY (sub-second), so a short grace
+// suffices and the confirm doubles as a swallow-guard. codex is 'socket-ack' (adapter.deliveryConfirm)
+// and never reaches this loop — its input queue is durable but it logs the user-input only at ingest
+// (tens of seconds into a long turn), so a grace would only false-FAIL a message that WILL be processed.
+// `IAP_HOST_LIVENESS_GRACE_MS` overrides (operator calibration; tests set 0 for an immediate
+// deterministic fail). Prefer a false-FAIL (sender retries) over a false-OK (silent loss, forbidden).
+const CONFIRM_GRACE_MS = 4000
+function confirmGraceMs(): number {
   const raw = process.env.IAP_HOST_LIVENESS_GRACE_MS
   const n = raw === undefined ? NaN : Number(raw)
   if (Number.isFinite(n) && n >= 0) return n
-  return runtime === 'codex' ? CONFIRM_GRACE_CODEX_MS : CONFIRM_GRACE_CLAUDE_MS
+  return CONFIRM_GRACE_MS
 }
 
 // Launchd-revive retry — a MISS on a launchd-managed target the daemon can't wake (H4)
@@ -204,13 +203,17 @@ export interface WarmDeliverSeam {
 }
 
 /**
- * Warm-deliver `envelope` to a LIVE local target over its supervisor socket (pty-only). Landing is
- * CONFIRMED MESSAGE-SPECIFICALLY — by a NEW transcript record CARRYING this envelope appearing past the
- * pre-deliver baseline, NOT the socket-ack (a flushed CR proves the bytes left us, not that the session
- * accepted them) and NOT a bare mtime advance (the receiver's OWN concurrent turn bumps mtime even when
- * our paste was swallowed — the false-OK class the contract forbids). A router (telegram/notifier) has
- * no transcript → confirmed by the socket-ack (liveness is structural via launchd KeepAlive). See
- * `deliverViaHost`.
+ * Warm-deliver `envelope` to a LIVE local target over its supervisor socket (pty-only). Confirmation is
+ * adapter-driven (RuntimeAdapter.deliveryConfirm):
+ *   - 'transcript' (claude): CONFIRMED MESSAGE-SPECIFICALLY — by a NEW transcript record CARRYING this
+ *     envelope appearing past the pre-deliver baseline, NOT the socket-ack (a flushed CR proves the
+ *     bytes left us, not that the session accepted them) and NOT a bare mtime advance (the receiver's
+ *     OWN concurrent turn bumps mtime even when our paste was swallowed — the false-OK class, forbidden).
+ *   - 'socket-ack' (codex): confirmed by the socket-ack — its input queue is durable (a mid-turn submit
+ *     is never lost) and it logs no prompt-acceptance record, so a transcript grace would only false-FAIL.
+ *   - router (telegram/notifier): no transcript → confirmed by the socket-ack (liveness is structural
+ *     via launchd KeepAlive).
+ * See `deliverViaHost`.
  */
 export async function deliverWarm(
   target: DeliveryTarget,
@@ -244,21 +247,32 @@ async function deliverViaHost(
   // router's liveness is structural via launchd KeepAlive (not a model turn), so the ack IS the
   // delivery-level confirm (parity with the legacy tmux router C-j path).
   if (adapter.kind === 'router') return ok(undefined)
+  // 'socket-ack' TUI runtimes (codex): the input queue is DURABLE — a mid-turn submit is HELD and
+  // processed at the next turn boundary, however long that is (verified live 2026-06-25: an 80s turn
+  // still ingested + replied; the send false-FAILed at the 8s grace, the message was NOT lost). codex
+  // writes NO prompt-acceptance record (its user-input lands only at ingest), so a transcript grace
+  // can't tell "swallowed" from "queued-but-not-yet-ingested" within any useful window — it only
+  // false-FAILs a message that WILL be delivered, wrongly escalating to a fallback peer. The flushed
+  // socket-ack above IS the delivery confirm; a genuinely dead session already failed at deliverHosted
+  // (no socket / stalled flush) → really-dead still escalates. (claude stays on the strict
+  // message-specific confirm below — it logs acceptance sub-second, so that is cheap AND catches a
+  // swallowed paste, the false-OK class.) Driven by adapter.deliveryConfirm, not a hardcoded runtime.
+  if (adapter.deliveryConfirm === 'socket-ack') return ok(undefined)
   // socket-ack ≠ landed. With no transcript (direct callers/tests without a cwd) we can only trust the
   // flushed submit — confirmed-only.
   if (!cwd || !baseline) return ok(undefined)
-  // MESSAGE-SPECIFIC landed-confirm — the false-OK killer. A bare transcript/pane-log mtime BUMP is
-  // NOT proof the session took THIS message: a receiver in an active turn advances both mtimes with
-  // its OWN rendering even when our paste was swallowed at the turn boundary (incident 2026-06-23:
-  // ok=true, message gone). The ONLY proof is a NEW transcript record CARRYING our envelope —
-  //   claude: a queue-operation `content` (busy → enqueued) or the user-turn message (idle),
-  //   codex:  a user-input response_item (written at model-turn-start, ~4-6s — hence the codex grace).
-  // The receiver's own assistant/tool turn never reproduces the `<iap from-personality=…>` wrapper, so
-  // it cannot forge a confirm. No such record within the grace → false-FAIL (the sender retries) — NOT
-  // a false-OK (silent loss the contract forbids).
+  // MESSAGE-SPECIFIC landed-confirm — the false-OK killer (claude / any 'transcript'-confirm runtime;
+  // codex took the socket-ack short-circuit above). A bare transcript/pane-log mtime BUMP is NOT proof
+  // the session took THIS message: a receiver in an active turn advances both mtimes with its OWN
+  // rendering even when our paste was swallowed at the turn boundary (incident 2026-06-23: ok=true,
+  // message gone). The ONLY proof is a NEW transcript record CARRYING our envelope — for claude, a
+  // queue-operation `content` (busy → enqueued) or the user-turn message (idle), written sub-second so
+  // a short grace covers it. The receiver's own assistant/tool turn never reproduces the
+  // `<iap from-personality=…>` wrapper, so it cannot forge a confirm. No such record within the grace →
+  // false-FAIL (the sender retries) — NOT a false-OK (silent loss the contract forbids).
   const confirm = seam.confirmLanded ?? ((payload: string) => transcriptCarriesEnvelope(baseline, payload))
   const sleep = seam.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)))
-  const graceMs = confirmGraceMs(target.runtime)
+  const graceMs = confirmGraceMs()
   const graceDeadline = monotonicMs() + graceMs
   while (true) {
     if (confirm(envelope)) return ok(undefined)