@agfpd/iapeer 0.2.95 → 0.2.97

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,24 @@ 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.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.95",
+  "version": "0.2.97",
   "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,7 +63,7 @@ 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 { MARKETPLACE_NAME, onboardHost, tccFullDiskAccessNote } from '../onboard/index.ts'
 import { readMemoryProvider } from '../status/index.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { pluginLogsDir } from '../storage/index.ts'
@@ -946,8 +946,8 @@ const USAGE = `usage: iapeer <verb> [args]
   version | --version | -v                                       print the installed binary's version
   help | --help | -h                                             print this usage (works appended to any verb; executes nothing)
   daemon [--install-plist]                                       run the host-wide HTTP-MCP router (launchd-held)
-  onboard [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]
-                                                                 backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES)
+  onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]
+                                                                 backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively
   status                                                         host snapshot: version, daemon health, memory slot (<provider> | none)
   install-runtime <runtime> [--package pkg] [--npx]              npx-install a runtime package + deploy its declared peer-set
   update-runtime <runtime> | --all [--force]                     version-gate → re-install + re-provision declared set → restart the runtime's peers
@@ -1002,6 +1002,18 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
   try {
     switch (verb) {
       case 'onboard': {
+        // SECURITY GATE (pre-release): the operator must consciously accept the risk of
+        // beta infra with live agents BEFORE onboard mutates the host. --accept-risk /
+        // IAPEER_ACCEPT_RISK accepts non-interactively (one-liner installers / CI); a
+        // TTY is prompted; a non-TTY without the flag is REFUSED with how-to (never a
+        // silent proceed / hang). SKIPPED for --dry-run (a read-only preview mutates
+        // nothing, so there is no risk to accept yet). Runs BEFORE daemon/peer steps.
+        if (flags['dry-run'] !== true) {
+          const { confirmOnboardRisk } = await import('../onboard/risk.ts')
+          const gate = await confirmOnboardRisk({ accept: flags['accept-risk'] === true, env, out, errOut })
+          if (gate === 'refused-non-tty') return 2 // explicit refusal: how-to printed
+          if (gate === 'declined') return 1 // operator said no
+        }
         // Host-phase: register OUR marketplace in claude + codex (IDEMPOTENT — detect
         // → skip when present; an already-configured host is a no-op). --dry-run
         // reports the would-be actions without touching anything. --infra <csv> ALSO
@@ -1084,6 +1096,10 @@ 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`)
+        // macOS TCC advisory (manual grant — no flag/setting can): gated on a memory provider, since a
+        // vault (often an iCloud Obsidian dir) is the TCC-protected resource. Base ~/.iapeer needs none.
+        const tcc = tccFullDiskAccessNote({ memoryActive: mem.provider != null })
+        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

@@ -117,6 +117,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 +147,8 @@ export const claudeAdapter: RuntimeAdapter = {
       '--dangerously-skip-permissions',
       '--disallowedTools',
       'AskUserQuestion',
+      '--add-dir',
+      '/',
       ...(spec.systemPromptFile ? ['--system-prompt-file', spec.systemPromptFile] : []),
       ...(spec.resume ? ['--continue'] : []),
       ...(spec.extraArgs ?? []),

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

@@ -212,3 +212,27 @@ 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 or settings key can grant — it is
+ * user-granted in System Settings, by design. `~/.iapeer` lives under $HOME and is NOT TCC-protected,
+ * so a BASE install needs nothing. The trigger that warrants the grant is a memory vault — commonly an
+ * iCloud Obsidian dir, and iCloud Drive / Desktop / Documents / Downloads ARE TCC-protected — so the
+ * note is GATED on a memory provider being present; a base ~/.iapeer-only host is never nagged.
+ * Returns null when not applicable (caller prints nothing). Pure (no I/O) — unit-testable.
+ */
+export function tccFullDiskAccessNote(opts: { memoryActive: boolean }): string | null {
+  if (!opts.memoryActive) return null
+  return (
+    [
+      'macOS Full Disk Access (manual — TCC cannot be set by any flag or settings key):',
+      '  ~/.iapeer needs none (it is under $HOME). BUT a memory vault or a peer work dir in a',
+      '  TCC-protected location (iCloud Drive, Desktop, Documents, Downloads — e.g. an iCloud',
+      '  Obsidian vault) does, or file tools silently fail to read/write there.',
+      '  Grant it to ~/.local/bin/iapeer (and to Terminal too, if you attach) in:',
+      '    System Settings → Privacy & Security → Full Disk Access',
+    ].join('\n') + '\n'
+  )
+}

package/src/onboard/risk.ts

@@ -0,0 +1,110 @@
+// Onboard security gate (pre-release): the operator must consciously accept the
+// risk of running beta infra with live agents BEFORE onboard mutates the host
+// (daemon start + peer registration). The warning text is the owner's verbatim
+// disclaimer — do NOT reword it.
+//
+// BOUNDARY: this must never break a NON-INTERACTIVE onboard (a one-liner installer /
+// automation calls onboard without a TTY). Acceptance paths:
+//   • --accept-risk (CLI flag) or IAPEER_ACCEPT_RISK=1 (env) → accept, no prompt
+//     (the explicit non-interactive channel);
+//   • a real TTY → show the warning and require a y/yes answer;
+//   • a NON-TTY without the flag → REFUSE with how-to (never a silent proceed, never
+//     a hang waiting on stdin that no one will type into).
+
+/** The owner's verbatim security disclaimer. Shown at the top of an interactive
+ *  onboard and in the non-interactive refusal. Word-for-word — do not edit. */
+export const ONBOARD_SECURITY_WARNING = `Security warning — please read.
+
+iapeer is beta infrastructure for live AI agents on your machine. Expect sharp edges.
+
+It starts a local daemon, registers peers, and routes messages between Claude Code,
+Codex CLI, Telegram humans, and services. If tools, memory, or project files are
+enabled, a bad prompt can make an agent do unsafe things.
+
+iapeer is not a hostile multi-user security boundary.
+Do not expose it to untrusted users, untrusted Telegram chats, or the public internet.
+
+State, profiles, logs, memory, and runtime configuration live under ~/.iapeer and
+peer-local .iapeer folders. Treat that data as sensitive.
+
+If you are not comfortable with local daemons, filesystem access, Telegram bot tokens,
+and agent tool permissions, do not continue.
+
+Recommended baseline:
+- localhost only;
+- private Telegram bots/chats only;
+- least-privilege project folders and tools;
+- no secrets in reachable files;
+- review peers, memory, logs, and configs after onboarding.
+
+I understand this is powerful and inherently risky. Continue?`
+
+/** How the onboard verb should react after the gate. */
+export type RiskGateResult =
+  | 'accepted-flag' // --accept-risk / IAPEER_ACCEPT_RISK → non-interactive accept (no prompt)
+  | 'accepted-prompt' // interactive TTY answered y/yes
+  | 'declined' // interactive TTY answered no → abort
+  | 'refused-non-tty' // no TTY and no accept flag → refuse with how-to (never proceed)
+
+export interface RiskGateOptions {
+  /** The --accept-risk CLI flag. */
+  accept?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Override TTY detection (tests). Default: stdin AND stdout are TTYs. */
+  isTty?: boolean
+  /** Injectable prompt (tests). Default: a readline question on the live TTY. */
+  ask?: () => Promise<string>
+  /** stdout sink (default process.stdout). */
+  out?: (s: string) => void
+  /** stderr sink (default process.stderr). */
+  errOut?: (s: string) => void
+}
+
+const RISK_ENV = 'IAPEER_ACCEPT_RISK'
+
+function envAccepts(env: NodeJS.ProcessEnv): boolean {
+  return /^(1|true|yes)$/i.test((env[RISK_ENV] ?? '').trim())
+}
+
+async function defaultAsk(): Promise<string> {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question('')).trim()
+  } finally {
+    rl.close()
+  }
+}
+
+/**
+ * Confirm the operator accepts the onboard risk. Returns the gate outcome; the
+ * caller maps a non-accept outcome to a non-zero exit. Never throws, never hangs a
+ * non-interactive run: the flag/env path is silent-accept, a TTY is prompted, a
+ * non-TTY without the flag is refused with the exact how-to.
+ */
+export async function confirmOnboardRisk(opts: RiskGateOptions = {}): Promise<RiskGateResult> {
+  const env = opts.env ?? process.env
+  const out = opts.out ?? ((s: string) => void process.stdout.write(s))
+  const errOut = opts.errOut ?? ((s: string) => void process.stderr.write(s))
+
+  // Non-interactive accept channel (one-liner installers / automation).
+  if (opts.accept === true || envAccepts(env)) return 'accepted-flag'
+
+  const tty = opts.isTty ?? (process.stdin.isTTY === true && process.stdout.isTTY === true)
+  if (!tty) {
+    // No one to answer the prompt — refuse LOUD with how-to, never a silent proceed.
+    errOut(
+      `${ONBOARD_SECURITY_WARNING}\n\n` +
+        `Non-interactive onboard: no TTY to confirm. Re-run with --accept-risk ` +
+        `(or set ${RISK_ENV}=1) to accept this risk explicitly.\n`,
+    )
+    return 'refused-non-tty'
+  }
+
+  out(`${ONBOARD_SECURITY_WARNING} `)
+  const ask = opts.ask ?? defaultAsk
+  const answer = (await ask()).trim().toLowerCase()
+  if (answer === 'y' || answer === 'yes') return 'accepted-prompt'
+  out('onboard aborted — risk not accepted.\n')
+  return 'declined'
+}