@agfpd/iapeer 0.2.96 → 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.96",
+  "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'
@@ -1096,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'
+  )
+}