@agfpd/iapeer 0.4.28 → 0.4.29

package/package.json

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