@agfpd/iapeer 0.4.27 → 0.4.29

package/package.json

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

@@ -240,6 +240,38 @@ export const claudeAdapter: RuntimeAdapter = {
     return null
   },
 
+  /**
+   * MID-SESSION nag/upsell auto-dismiss (livability — distinct from bootDialogKeys,
+   * which the supervisor drives only until ready). claude pops a ONE-TIME interactive
+   * upsell modal AFTER the session is live that BLOCKS a headless peer (no human to
+   * answer):
+   *
+   *     Try the new fullscreen renderer?
+   *     · Flicker-free output …
+   *     ❯ 1. Yes, try it
+   *       2. Not now
+   *     Enter to confirm · Esc to cancel
+   *
+   * The default cursor sits on "1. Yes, try it", so a BARE Enter would ENABLE the
+   * fullscreen renderer — which switches claude to the alt-screen TUI and changes the
+   * surface the pane-log model + composer-occupancy + ready-gate all read off. We must
+   * DECLINE: type the literal '2' then Enter ('2','Enter' → "2\r"; '2' is not a named/
+   * cursor key, so it is emitted verbatim without a `-l` literal switch — and `-l`
+   * would wrongly make the following 'Enter' literal too). VERIFIED-SAFE on the live
+   * fleet: '2'+Enter cleared the modal on boris and doc and returned them to the
+   * composer; an arrow-step+Enter MIS-FIRED into "tui":"fullscreen" on scriber, and Esc/
+   * 'n' are unverified — so this is the ONLY accepted sequence. Match the FULL signature
+   * (title AND the "2. Not now" decline row) so a transcript merely DISCUSSING the
+   * fullscreen renderer can never trigger a stray keystroke. Future one-time CC upsells
+   * of this class extend the match here (each with its own verified-safe decline key).
+   */
+  nagDismissKeys(pane: string): string[] | null {
+    if (pane.includes('Try the new fullscreen renderer?') && pane.includes('2. Not now')) {
+      return ['2', 'Enter']
+    }
+    return null
+  },
+
   /**
    * Ready for the first message iff the input surface is rendered AND no startup
    * dialog is still up (lifecycle.claudeInputReady, index.ts:272-279;

package/src/launch/types.ts

@@ -259,6 +259,20 @@ export interface RuntimeAdapter {
    */
   bootDialogKeys(pane: string): string[] | null
 
+  /**
+   * MID-SESSION nag/upsell auto-dismiss (livability). Distinct from bootDialogKeys:
+   * the boot-driver stops at ready, but claude/codex can pop a ONE-TIME interactive
+   * upsell modal AFTER the session is live (e.g. "Try the new fullscreen renderer?")
+   * that BLOCKS the pty waiting for a keypress no headless peer answers — it froze the
+   * live fleet until a human cleared it. A persistent supervisor watcher (daemon.ts)
+   * runs THIS off the authoritative model for the whole session and writes the keys.
+   * Return the send-keys args that dismiss with the VERIFIED-SAFE default (decline),
+   * else null. Match the FULL modal signature so ordinary content mentioning the
+   * feature can never trigger a stray keystroke into the composer. Optional — a runtime
+   * with no known mid-session nags (codex/router) omits it. tui only.
+   */
+  nagDismissKeys?(pane: string): string[] | null
+
   /** Is the input surface ready for the first message? (tui: ready marker present
    *  AND startup dialogs gone). Router runtimes return true (no input surface). */
   isInputReady(pane: string): boolean

package/src/supervisor/boot.ts

@@ -32,3 +32,25 @@ export function nextBootAction(adapter: BootPredicates, viewport: string, enc: K
   if (adapter.isInputReady(viewport)) return { kind: 'ready' }
   return { kind: 'wait' }
 }
+
+/** The slice of a RuntimeAdapter the MID-SESSION nag-watcher consumes — the optional
+ *  nagDismissKeys (claudeAdapter satisfies it; codex/router omit it → no nags). */
+export interface NagPredicate {
+  nagDismissKeys?(pane: string): string[] | null
+}
+
+export type NagAction = { kind: 'dismiss'; keys: string[]; bytes: Buffer } | { kind: 'none' }
+
+/**
+ * MID-SESSION nag/upsell step (livability) — the persistent sibling of nextBootAction. Unlike the
+ * boot-driver, which STOPS at ready, the daemon loops this for the WHOLE session: a one-time CC upsell
+ * modal (e.g. "Try the new fullscreen renderer?") can pop AFTER the session is live and BLOCK the pty on
+ * a keypress no headless peer answers. If the adapter recognizes the (FULL-signature) modal it returns
+ * the verified-safe DECLINE keys; the caller writes `action.bytes` to the pty (cooldown-guarded so a
+ * cleared modal is never double-answered). An adapter with no nagDismissKeys → always 'none'.
+ */
+export function nextNagAction(adapter: NagPredicate, viewport: string, enc: KeyEncoding = {}): NagAction {
+  const keys = adapter.nagDismissKeys?.(viewport)
+  if (keys && keys.length) return { kind: 'dismiss', keys, bytes: keysToBytes(keys, enc) }
+  return { kind: 'none' }
+}

package/src/supervisor/daemon.ts

@@ -25,7 +25,7 @@ import {
   stripQueries,
 } from './protocol.ts'
 import { attachedPath, geometryPath, pidPath, servePath, sockPath, writeGeometry } from './paths.ts'
-import { nextBootAction, type BootPredicates } from './boot.ts'
+import { nextBootAction, nextNagAction, type BootPredicates, type NagPredicate } from './boot.ts'
 import { modelToPlainText } from './render.ts'
 import { codexAdapter } from '../launch/adapters/codex.ts'
 import { claudeAdapter } from '../launch/adapters/claude.ts'
@@ -80,6 +80,12 @@ const BOOT_POLL_MS = 2000
 // Stop driving after this long even if readiness is never observed (a hung/unknown startup); the
 // driver is best-effort and never blocks the conduit, which keeps serving regardless.
 const BOOT_DRIVE_MS = 120_000
+// MID-SESSION nag-watcher cadence: same 2 s model poll as the boot-driver. After answering a nag, hold
+// this long before the next check so a just-dismissed modal (claude repaints it away within a frame) is
+// never re-answered — a stray keystroke would land in the now-visible composer. If the modal genuinely
+// survives the hold (our key did not take), the next tick re-fires, so retries stay bounded, not lost.
+const NAG_POLL_MS = 2000
+const NAG_COOLDOWN_MS = 4000
 
 // Bun-native PTY (Bun ≥1.3.5) is not yet in @types/bun — type the slice we use.
 interface PtyChild {
@@ -541,4 +547,38 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     }, BOOT_POLL_MS)
     ;(driver as { unref?: () => void }).unref?.()
   }
+
+  // ── mid-session nag-watcher (livability) ────────────────────────────────────────
+  // The boot-driver above STOPS at ready. But claude/codex can pop a ONE-TIME upsell modal
+  // MID-SESSION (e.g. "Try the new fullscreen renderer?", which appears on the return-to-prompt
+  // boundary after a tool result) that BLOCKS the pty on a keypress no headless peer answers — it
+  // froze live fleet peers (boris, doc) until a human cleared it by hand. A PERSISTENT watcher answers
+  // the curated, verified-safe DECLINE for that class off the SAME authoritative @xterm model, for the
+  // WHOLE session lifetime, exactly like the boot-driver answers startup dialogs — model-read
+  // (modelToPlainText) + raw pty-byte-write (keysToBytes). Cooldown-guarded: after firing, hold
+  // NAG_COOLDOWN_MS so a just-dismissed modal is never double-answered (a stray keystroke would land in
+  // the now-visible composer). Only runs for a runtime whose adapter declares nagDismissKeys.
+  const nagAdapter = BOOT_ADAPTERS[runtime] as NagPredicate | undefined
+  if (nagAdapter?.nagDismissKeys) {
+    let nagFiredMs = 0
+    const nagWatch = setInterval(() => {
+      if (down) {
+        clearInterval(nagWatch)
+        return
+      }
+      if (Date.now() - nagFiredMs < NAG_COOLDOWN_MS) return // let a just-answered modal repaint away first
+      let action
+      try {
+        const enc = { appCursorKeys: xterm.modes.applicationCursorKeysMode }
+        action = nextNagAction(nagAdapter, modelToPlainText(xterm, cols, rows), enc)
+      } catch {
+        return // transient model read — retry next tick
+      }
+      if (action.kind === 'dismiss') {
+        child.terminal.write(action.bytes)
+        nagFiredMs = Date.now()
+      }
+    }, NAG_POLL_MS)
+    ;(nagWatch as { unref?: () => void }).unref?.()
+  }
 }