@agfpd/iapeer 0.2.96 → 0.2.98

package/README.md

@@ -34,7 +34,7 @@ iapeer onboard
 # 3. create your first agent
 iapeer create assistant --runtime claude
 
-# 4. talk to it live in your terminal — detach with Ctrl-]
+# 4. talk to it live in your terminal — detach with Ctrl-] (or just close it; the agent keeps running)
 iapeer attach assistant
 ```
 
@@ -49,7 +49,7 @@ The peer's name is the folder name, normalized (`myagent`). `create` sets up a f
 
 Two ways to work with an agent locally in your terminal:
 
-- **Join its live session** — `iapeer attach assistant`. The daemon wakes the peer first if it is asleep; detach with `Ctrl-]` and the session keeps running.
+- **Join its live session** — `iapeer attach assistant`. The daemon wakes the peer first if it is asleep. Detach with `Ctrl-]` — or just close the terminal — and the session keeps running in the background; reattach with `iapeer attach` whenever you need it.
 - **Open a fresh session in the peer's folder** — go to the peer's directory and launch its runtime:
 
   ```sh
@@ -63,14 +63,25 @@ Agents reach each other with `send_to_peer`; you can also message any peer over
 
 ## What makes it different
 
-- **Real interactive CLI sessions, not headless one-shots.** Each AI peer is a full Claude Code or Codex CLI session, not a disposable `claude -p` / `codex exec` call.
+- **Real interactive CLI sessions, not headless one-shots.** Each AI peer is a full Claude Code or Codex CLI session, not a disposable `claude -p` / `codex exec` call (as of 2026-06-15, `claude -p` no longer counts against the subscription's main usage limits).
 - **Warm-on-demand lifecycle.** A live session answers fast; after about an hour idle the daemon closes it; the next message brings it back with its context resumed. The message flow drives the lifecycle — not a human's presence.
 - **One identity across runtimes, with one memory.** A peer's `personality` is decoupled from its runtime — the same peer runs on Claude or Codex, switched with a command. By default (set up by `iapeer onboard`) it carries one shared memory (iapeer-memory) keyed to the personality, not the runtime: one personality, one memory, whatever runtime it runs on.
 - **Heterogeneous peers, one protocol.** AI agents, humans (Telegram), and services (timer = cron, watcher = event) are all first-class, addressed the same way over an always-on MCP daemon that exposes exactly one tool, `send_to_peer`.
 
 ## Documentation
 
-[`docs/`](https://github.com/agfpd/iapeer/tree/main/docs) — the product side (what it is and how to use it); [`docs/internals/`](https://github.com/agfpd/iapeer/tree/main/docs/internals) — the mechanics from the inside. This repository is the implementation.
+[`docs/`](docs/README.md) — the product side: what it is and how to use it. Available in two languages — English (default) and [Русский](docs/ru/README.md). This repository is the implementation.
+
+## Roadmap
+
+Planned, not yet built:
+
+- **Web UI** — a browser interface for working with the team.
+- **Linux support** — iapeer runs on macOS today; Linux is planned.
+- **More agent runtimes** — `opencode` and `antigravity`, two further CLI runtimes alongside Claude Code and Codex.
+- **Discord runtime** — a human-presence runtime for Discord, alongside Telegram.
+- **Permissions gate** — finer control over what an agent is allowed to do.
+- **Approve permissions over Telegram** — approve an agent's permission requests from the chat; today permissions are auto-allowed by flags.
 
 ## License
 

package/package.json

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

package/src/cli/index.ts

@@ -63,8 +63,8 @@ import {
 } from '../identity/profileStandard.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
 import { ensureDaemonStarted, installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
-import { MARKETPLACE_NAME, onboardHost } from '../onboard/index.ts'
-import { readMemoryProvider } from '../status/index.ts'
+import { MARKETPLACE_NAME, onboardHost, runtimeAuthNote, tccFullDiskAccessNote } from '../onboard/index.ts'
+import { probeFullDiskAccess, readMemoryProvider } from '../status/index.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { pluginLogsDir } from '../storage/index.ts'
 
@@ -1096,6 +1096,23 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
         out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
+        // Runtime auth readiness (clean-host prerequisite): a peer runs the runtime's
+        // interactive TUI; the launcher auto-clears first-run modals (theme/trust) but
+        // CANNOT complete a login OAuth flow. Warn for every INSTALLED runtime (marketplace
+        // state != runtime-missing) that has no positive auth evidence — before it ships a
+        // peer that would fail to wake on the login screen.
+        for (const m of r.marketplaces) {
+          if (m.state === 'runtime-missing') continue
+          const authNote = runtimeAuthNote(m.runtime, env)
+          if (authNote) errOut(authNote + '\n')
+        }
+        // macOS TCC advisory (manual grant — no flag/setting/script can): PROBE-DRIVEN, not
+        // memory-gated — a missing grant silently breaks file I/O (EPERM, no prompt/hang) on
+        // any TCC-protected path (iCloud vault, Documents/Desktop/Downloads peer cwd). Silent
+        // when granted / non-macOS / undeterminable.
+        const { iapeerBinPath } = await import('../install/index.ts')
+        const tcc = tccFullDiskAccessNote({ fda: probeFullDiskAccess(env), binPath: iapeerBinPath(env) })
+        if (tcc) out(tcc)
         return daemonFailed || r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
       }
       case 'native-memory': {

package/src/launch/adapters/claude.ts

@@ -49,6 +49,12 @@ const CLAUDE_BOOT_DIALOG_MARKERS = [
   'I am using this for local development',
   'Resume from summary',
   'Resuming the full session',
+  // First-run theme picker ("Let's get started. Choose the text style…") — appears
+  // on a CLEAN host (fresh config dir) BEFORE the input prompt, verified live on
+  // claude 2.1.181 in a pty. NOT removed by --dangerously-skip-permissions; if not
+  // cleared the peer never reaches ready. (There is NO separate "accept dangerous
+  // permissions" screen in 2.1.181 — verified absent.)
+  'Choose the text style',
 ] as const
 
 function anyBootDialog(pane: string): boolean {
@@ -117,6 +123,14 @@ export const claudeAdapter: RuntimeAdapter = {
    *     owner watches; the question goes "into the void". Default is the literal
    *     'AskUserQuestion'; the per-peer override (PEER_DISALLOWED_TOOLS empty =
    *     allow all) is install-time launch.env, not this path.
+   *   - '--add-dir','/'  grants the file/edit/bash tools access OUTSIDE cwd (the
+   *     CLI equivalent of settings `permissions.additionalDirectories`). A peer
+   *     reads/writes its memory vault (often an iCloud Obsidian dir) and ~/.iapeer,
+   *     both outside cwd. Passing it as a LAUNCH FLAG means a clean host needs NO
+   *     manual `additionalDirectories` in the user's ~/.claude/settings.json — the
+   *     requirement travels with the launch, reversible, no user-file mutation.
+   *     (OS-level access to TCC-protected dirs — iCloud / Desktop / Documents — is
+   *     a SEPARATE macOS grant, not coverable by any flag; onboard instructs it.)
    *   - '--system-prompt-file', spec.systemPromptFile  claude-start.sh:318 —
    *     ONLY when set (a tui runtime that usesDoctrine composes one). Swaps the
    *     CC coding baseline for the merged peer doctrine; plugin/MCP/CLAUDE.md
@@ -139,6 +153,8 @@ export const claudeAdapter: RuntimeAdapter = {
       '--dangerously-skip-permissions',
       '--disallowedTools',
       'AskUserQuestion',
+      '--add-dir',
+      '/',
       ...(spec.systemPromptFile ? ['--system-prompt-file', spec.systemPromptFile] : []),
       ...(spec.resume ? ['--continue'] : []),
       ...(spec.extraArgs ?? []),
@@ -175,7 +191,16 @@ export const claudeAdapter: RuntimeAdapter = {
     if (
       pane.includes('trust this folder') ||
       pane.includes('Allow external CLAUDE.md file imports?') ||
-      pane.includes('I am using this for local development')
+      pane.includes('I am using this for local development') ||
+      // First-run theme picker (clean host): the default-highlighted row is always a
+      // valid theme (any choice is harmless for a headless peer), so a bare Enter
+      // accepts it. Without this the picker blocks the boot forever on a fresh host.
+      // NOTE: the LOGIN method picker that can follow on an UNAUTHENTICATED host is
+      // deliberately NOT auto-answered — selecting subscription opens a browser OAuth
+      // flow no headless peer can complete. Login is an onboard PREREQUISITE
+      // (ANTHROPIC_API_KEY or a one-time `claude login`); a never-authed host fails
+      // the wake LOUD at the boot deadline rather than auto-entering a dead OAuth.
+      pane.includes('Choose the text style')
     ) {
       return ['Enter']
     }

package/src/launch/index.ts

@@ -13,7 +13,7 @@
 // marketplace / plugin install / update — that is install-time). lifecycle
 // decides WHEN/HOW-MANY and hands launch a fully-resolved LaunchSpec + adapter.
 
-import { mkdirSync } from 'fs'
+import { existsSync, mkdirSync, statSync } from 'fs'
 import { dirname } from 'path'
 import { spawnSync } from 'child_process'
 import { type Runtime } from '../core/constants.ts'
@@ -268,6 +268,13 @@ export const launch: LaunchFn = async (
     const invocation = buildLaunchInvocation(spec, adapter, cfg)
     mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 }) // the supervisor writes the pane-log here
     const paneLogPath = `${cfg.logDir}/${identity}.log`
+    // SESSION-START BOUNDARY (premature-ready fix): the pane-log is a SHARED append-only file across a
+    // peer's session lineage. Capture its size BEFORE the supervisor opens+writes it, so the hosted
+    // ready-gate (waitHostReady → paneLogViewport) renders ONLY this session's bytes — never a PRIOR
+    // session's last frame, which (a `❯ ready` row) would satisfy isInputReady before the fresh runtime
+    // has painted → a premature deliver into a still-booting session → the first message is LOST and the
+    // model never produces a turn. Captured here, before startPtyHost spawns the writer (single writer).
+    const paneLogStartByte = existsSync(paneLogPath) ? statSync(paneLogPath).size : 0
     const host = await startPtyHost({
       identity,
       runtime: spec.runtime,
@@ -293,11 +300,25 @@ export const launch: LaunchFn = async (
       // the SAME shape as the tmux boot/deliver/ready-gate below, with host equivalents.
       const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
       const isReady = await waitHostReady(
-        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs },
+        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte },
         sleep,
       )
       if (!isReady) return fail(identity, 'never-became-ready (hosted: supervisor input surface not ready)')
       if (firstMessage.trim().length === 0) return ready(identity) // bare bring-up — no message to deliver
+      // INSTRUMENTATION (premature-ready diagnosis): record the session-start boundary and how much THIS
+      // session had written into the shared pane-log by the time the ready-gate fired. On a recurrence,
+      // paneLogBytes ≈ paneLogStartByte (ready seen though the new session wrote ~nothing) localizes a
+      // residual stale-frame read; a healthy fresh boot writes well beyond startByte before readiness.
+      appendLifecycleEvent(
+        cfg.exitLogDir,
+        {
+          ev: 'hosted-deliver',
+          identity,
+          paneLogStartByte,
+          paneLogBytes: existsSync(paneLogPath) ? statSync(paneLogPath).size : 0,
+        },
+        { env },
+      )
       const d = await deliverHosted(identity, firstMessage)
       if (!d.ok) return fail(identity, `hosted deliver failed: ${d.error}`)
       const readyDeadline = Date.now() + cfg.readyGateSecs * 1000

package/src/launch/ptyHost.ts

@@ -160,15 +160,20 @@ export async function startPtyHost(b: {
  * 2 s cadence + bootDeadline.
  */
 export async function waitHostReady(
-  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number },
+  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number },
   sleep: (ms: number) => Promise<void>,
 ): Promise<boolean> {
   const log = `${b.logDir}/${b.identity}.log`
   const iters = Math.max(1, Math.ceil(b.bootDeadlineSecs / 2))
+  // paneLogStartByte = the pane-log size at THIS session's spawn (captured by launch before the
+  // supervisor opens the shared append-only log). Passing it to the model render confines readiness to
+  // bytes THIS session wrote — without it a prior session's trailing `❯ ready` frame in the shared log
+  // satisfies isInputReady before the fresh runtime paints, causing a premature deliver into a booting
+  // session (the first message is then lost). See readyGateModel.loadPaneLogModel.
   for (let i = 0; i < iters; i++) {
     await sleep(2000)
     if (!hostSessionAlive(b.identity)) return false
-    const view = await paneLogViewport(log, HOST_COLS, HOST_ROWS)
+    const view = await paneLogViewport(log, HOST_COLS, HOST_ROWS, b.paneLogStartByte ?? 0)
     if (view && b.adapter.isInputReady(view)) return true
   }
   return false

package/src/launch/readyGateModel.ts

@@ -89,14 +89,25 @@ export async function readyGateViewport(opts: ReadyGateViewportOpts): Promise<st
  * (unreadable/short log, @xterm hiccup) — the caller decides the fallback (capture-pane for the
  * readygate flip; a retry/fail for hosted).
  */
-async function loadPaneLogModel(log: string, cols: number, rows: number): Promise<Terminal | null> {
+async function loadPaneLogModel(log: string, cols: number, rows: number, startByte = 0): Promise<Terminal | null> {
   if (!(cols > 0 && rows > 0) || !existsSync(log)) return null
   try {
     const { Terminal } = await import('@xterm/headless')
     const fd = openSync(log, 'r')
     try {
       const sz = fstatSync(fd).size
-      const off = Math.max(0, sz - SEED_BYTES)
+      // RENDER WINDOW = the SEED tail (last 4 MiB) AND, when given, the SESSION-START boundary. The
+      // pane-log is a SHARED append-only file across a peer's session lineage, so its tail can carry a
+      // PRIOR session's last frame — and a prior session almost always ended idle at a `❯ ready` row.
+      // Rendering that on a FRESH wake (before the new runtime has painted) makes isInputReady=true
+      // PREMATURELY → the gate delivers into a still-booting session → the first message is LOST and the
+      // model never produces a turn ("no activity advance"). `startByte` = the pane-log size captured at
+      // THIS session's spawn; clamping `off` to it renders ONLY this session's bytes, never the prior
+      // frame. Trim-safety: if capPaneLogs shrank the file BELOW startByte since capture (rare, mid-boot),
+      // the boundary is stale → fall back to the SEED tail (no worse than pre-fix; never hang on a 0-len
+      // read). startByte=0 (default) is byte-identical to the prior behavior.
+      const seedFloor = Math.max(0, sz - SEED_BYTES)
+      const off = startByte > 0 && startByte <= sz ? Math.max(startByte, seedFloor) : seedFloor
       const buf = Buffer.alloc(sz - off)
       readSync(fd, buf, 0, buf.length, off)
       const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 3000 })
@@ -110,8 +121,8 @@ async function loadPaneLogModel(log: string, cols: number, rows: number): Promis
   }
 }
 
-export async function paneLogViewport(log: string, cols: number, rows: number): Promise<string | null> {
-  const term = await loadPaneLogModel(log, cols, rows)
+export async function paneLogViewport(log: string, cols: number, rows: number, startByte = 0): Promise<string | null> {
+  const term = await loadPaneLogModel(log, cols, rows, startByte)
   if (!term) return null
   const { modelToPlainText } = await import('../shadow/render.ts')
   return modelToPlainText(term, cols, rows)

package/src/onboard/index.ts

@@ -12,7 +12,7 @@
 import { spawnSync } from 'child_process'
 import { homedir } from 'os'
 import { join } from 'path'
-import { accessSync, constants as FS } from 'fs'
+import { accessSync, constants as FS, existsSync, readFileSync } from 'fs'
 
 /** OUR marketplace — GitHub owner/repo, the source both runtimes' `marketplace add`
  *  takes; and the registered NAME both runtimes' `marketplace list` shows. */
@@ -212,3 +212,124 @@ export function onboardHost(opts: OnboardOptions = {}): OnboardResult {
   const noop = marketplaces.every(m => m.state !== 'registered')
   return { marketplaces, noop }
 }
+
+/**
+ * macOS Full Disk Access (TCC) advisory printed at the END of onboard. The runtime permission layer
+ * (`--add-dir` / `additionalDirectories` for claude, the sandbox flags for codex) governs what the
+ * RUNTIME allows; macOS TCC is a SEPARATE OS layer that NO flag, settings key, config, env var or
+ * script can grant — it is user-granted in System Settings, by design (the TCC db is SIP-protected).
+ *
+ * PROBE-DRIVEN, not memory-gated (was: gated on a memory provider). The advisory now fires off the
+ * REAL FDA state (`fda` from probeFullDiskAccess), because a missing grant is a latent fault no proxy
+ * captures: the DEFAULT memory vault is an iCloud Obsidian dir AND a peer work dir can itself sit in a
+ * protected location (Documents/Desktop/Downloads) with NO memory provider at all. So: grant present
+ * → silent; grant ABSENT on macOS → warn, every time.
+ *
+ * Failure mode is SILENT, not a hang: per Apple (DTS/Quinn, devforums 678819) a launchd-spawned CLI
+ * with no GUI front gets NO TCC dialog — the access is denied with EPERM. A peer therefore does NOT
+ * block; its file I/O on a protected path just silently fails. `~/.iapeer` (under $HOME) is NOT
+ * TCC-protected and needs nothing.
+ *
+ * Returns null when granted / undeterminable / non-macOS (`fda` true or null). Pure (no I/O) —
+ * the FDA probe and binPath are injected by the caller, so this stays unit-testable.
+ */
+export function tccFullDiskAccessNote(opts: { fda: boolean | null; binPath: string }): string | null {
+  if (opts.fda !== false) return null // granted, non-macOS, or undeterminable → nothing to nag
+  return (
+    [
+      'macOS Full Disk Access NOT granted (manual — TCC cannot be set by any flag, settings key or script):',
+      '  Without it, file I/O on TCC-protected paths SILENTLY FAILS with EPERM (no prompt, no hang) —',
+      '  a peer reading/writing an iCloud Obsidian vault (iCloud Drive / Desktop / Documents / Downloads)',
+      '  just gets denied. `~/.iapeer` itself is under $HOME and needs nothing.',
+      `  Grant it to ${opts.binPath} (and to Terminal too, if you attach) in:`,
+      '    System Settings → Privacy & Security → Full Disk Access',
+    ].join('\n') + '\n'
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runtime auth readiness — the one CLEAN-HOST modal a launcher CANNOT auto-clear
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// A headless peer runs the runtime's INTERACTIVE TUI (a pty), not `-p`. On a clean
+// host the first-run flow blocks on modals; the launcher auto-answers the ones it
+// recognizes (theme picker, folder-trust, …) — but the LOGIN screen cannot be
+// auto-answered (selecting subscription opens a browser OAuth flow no headless peer
+// can complete). So login is a PREREQUISITE: the host must be authenticated BEFORE
+// the first peer launches, or that peer's wake fails loud at the boot deadline.
+//
+// These probes are CONSERVATIVE: they return ready ONLY on positive evidence, so a
+// missing signal nags (one harmless advisory line) rather than letting an
+// unauthenticated host silently ship a peer that will fail to wake.
+
+/** Resolve claude's config dir (CLAUDE_CONFIG_DIR override, else ~/.claude). */
+function claudeConfigDir(env: NodeJS.ProcessEnv): string {
+  const override = env.CLAUDE_CONFIG_DIR?.trim()
+  if (override) return override
+  return join(env.HOME?.trim() || homedir(), '.claude')
+}
+
+/**
+ * True when claude is authenticated for a headless launch (won't block on the login
+ * picker). Positive evidence, in order: an auth env var; a completed onboarding +
+ * account in `~/.claude.json` (the subscription `claude login` path); or an
+ * `apiKeyHelper` in settings.json. Anything else → not ready (nag). Reads are
+ * env-rooted (HOME/CLAUDE_CONFIG_DIR) so a hermetic test isolates them.
+ */
+export function claudeAuthReady(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.ANTHROPIC_API_KEY?.trim() || env.ANTHROPIC_AUTH_TOKEN?.trim() || env.CLAUDE_CODE_OAUTH_TOKEN?.trim()) {
+    return true
+  }
+  // `~/.claude.json` lives at HOME root (not inside the config dir) in the default
+  // layout the fleet uses; hasCompletedOnboarding + an account/key marker proves the
+  // first-run flow (theme + login) is done.
+  const statePath = join(env.HOME?.trim() || homedir(), '.claude.json')
+  try {
+    const j = JSON.parse(readFileSync(statePath, 'utf8')) as Record<string, unknown>
+    if (j.hasCompletedOnboarding === true && (j.oauthAccount != null || j.customApiKeyResponses != null)) return true
+  } catch {
+    /* absent/unreadable → fall through to settings */
+  }
+  try {
+    const s = JSON.parse(readFileSync(join(claudeConfigDir(env), 'settings.json'), 'utf8')) as Record<string, unknown>
+    if (typeof s.apiKeyHelper === 'string' && s.apiKeyHelper.trim()) return true
+  } catch {
+    /* no settings / no helper */
+  }
+  return false
+}
+
+/**
+ * True when codex is authenticated (won't block / error at startup). Positive
+ * evidence: `OPENAI_API_KEY` env, or an `auth.json` under $CODEX_HOME/~/.codex.
+ * Env-rooted for hermetic tests.
+ */
+export function codexAuthReady(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.OPENAI_API_KEY?.trim()) return true
+  const codexHome = env.CODEX_HOME?.trim()
+  const authPath = codexHome
+    ? join(codexHome, 'auth.json')
+    : join(env.HOME?.trim() || homedir(), '.codex', 'auth.json')
+  return existsSync(authPath)
+}
+
+/**
+ * Advisory line for a runtime that is NOT authenticated (so the operator fixes it
+ * BEFORE launching peers). Returns null when the runtime is ready. Pure dispatch
+ * over the per-runtime probes above.
+ */
+export function runtimeAuthNote(runtime: OnboardRuntime, env: NodeJS.ProcessEnv = process.env): string | null {
+  if (runtime === 'claude') {
+    if (claudeAuthReady(env)) return null
+    return (
+      'claude: NOT authenticated — the first peer would block on the login screen (a launcher cannot\n' +
+      '  complete the browser OAuth flow). Before launching peers, either run `claude` once in your\n' +
+      '  terminal to sign in (subscription), or set ANTHROPIC_API_KEY in the daemon environment.'
+    )
+  }
+  if (codexAuthReady(env)) return null
+  return (
+    'codex: NOT authenticated — the first codex peer cannot reach the model. Before launching codex\n' +
+    '  peers, run `codex login` once (or set OPENAI_API_KEY in the daemon environment).'
+  )
+}