@agfpd/iapeer 0.4.83 → 0.4.84

package/docs/14-configuration-and-logs.md

@@ -61,6 +61,8 @@ The daemon's supervisory tick is fixed — once a minute, not configurable.
 | `IAPEER_LIFECYCLE_LOG_KEEP` | `5` | How many `lifecycle.log` rotations to keep. |
 | `IAPEER_DELIVERY_LOG_MAX_BYTES` | `5 MiB` | The `delivery.log` size for rotation. |
 | `IAPEER_DELIVERY_LOG_KEEP` | `5` | How many `delivery.log` rotations to keep. |
+| `IAPEER_PANELOG_MAX_BYTES` | `16 MiB` | The per-peer pane-log (`logs/lifecycle/<runtime>-<peer>.log`, the raw terminal byte stream) size at which rotation happens. |
+| `IAPEER_PANELOG_KEEP` | `2` | How many rotated pane-log copies to keep (`<log>.1` newest … `.N`). |
 | `IAPEER_SUPERVISE_LOG_VERBOSE` | off | A verbose log of supervisory ticks (by default only decisions are written, not routine "doing nothing"). |
 | `IAPEER_DAEMON_LOG` | off | An extended daemon log. |
 
@@ -80,6 +82,8 @@ The daemon keeps three durable logs in `~/.iapeer/logs/iapeer/`:
 - **`delivery.log`** — the outcome of each delivery: who, to whom, into which runtime, the result, sizes, topic. Metadata only — **the message body is not written**.
 - **`exits.log`** — session deaths with postmortem data: the supervisor records the cause (exit code / signal) at the moment a session dies.
 
+Per-peer **pane-logs** live separately under `~/.iapeer/logs/lifecycle/<runtime>-<peer>.log` — the raw terminal (pty) byte stream the supervisor appends for a session's whole life (occupancy/typing detection, the boot ready-gate, and `tail`-based monitors read them). They are rotated on the supervise tick by **copytruncate** (`IAPEER_PANELOG_MAX_BYTES` × `IAPEER_PANELOG_KEEP`, default 16 MiB × 2): the base file keeps its path and inode (its last 8 MiB tail is retained in place, so the live writer and every reader are undisturbed) while the preceding window is promoted to `<log>.1` … `.N`. Total per peer is bounded by roughly `MAX_BYTES × (KEEP + 1)`.
+
 ### Postmortem diagnostics
 
 The cause of a session's death (exit code / signal) the supervisor records at the moment of death to `exits.log` — what an ordinary "is the process alive" check misses. It's the material for answering "why did the agent die".

package/docs/ru/14-/320/272/320/276/320/275/321/204/320/270/320/263/321/203/321/200/320/260/321/206/320/270/321/217-/320/270-/320/266/321/203/321/200/320/275/320/260/320/273/321/213.md

@@ -61,6 +61,8 @@
 | `IAPEER_LIFECYCLE_LOG_KEEP` | `5` | Сколько ротаций `lifecycle.log` хранить. |
 | `IAPEER_DELIVERY_LOG_MAX_BYTES` | `5 МиБ` | Размер `delivery.log` для ротации. |
 | `IAPEER_DELIVERY_LOG_KEEP` | `5` | Сколько ротаций `delivery.log` хранить. |
+| `IAPEER_PANELOG_MAX_BYTES` | `16 МиБ` | Размер пер-пирового pane-лога (`logs/lifecycle/<runtime>-<peer>.log`, сырой байтовый поток терминала), при котором происходит ротация. |
+| `IAPEER_PANELOG_KEEP` | `2` | Сколько ротированных копий pane-лога хранить (`<log>.1` — свежайшая … `.N`). |
 | `IAPEER_SUPERVISE_LOG_VERBOSE` | выкл. | Подробный лог надзорных тиков (по умолчанию пишутся только решения, не рутинные «ничего не делаю»). |
 | `IAPEER_DAEMON_LOG` | выкл. | Расширенный лог демона. |
 
@@ -80,6 +82,8 @@
 - **`delivery.log`** — исход каждой доставки: кто, кому, в какой рантайм, результат, размеры, тема. Только метаданные — **тело сообщения не пишется**.
 - **`exits.log`** — смерти сессий с посмертными данными: супервизор фиксирует причину (код выхода / сигнал) в момент смерти сессии.
 
+Пер-пировые **pane-логи** лежат отдельно в `~/.iapeer/logs/lifecycle/<runtime>-<peer>.log` — сырой байтовый поток терминала (pty), который супервизор дописывает всю жизнь сессии (его читают детект занятости/typing, boot ready-gate и `tail`-мониторы). Они ротируются на надзорном тике методом **copytruncate** (`IAPEER_PANELOG_MAX_BYTES` × `IAPEER_PANELOG_KEEP`, по умолчанию 16 МиБ × 2): базовый файл сохраняет путь и inode (его последние 8 МиБ остаются на месте, поэтому живой писатель и все читатели не задеты), а предшествующее окно повышается в `<log>.1` … `.N`. Суммарный объём на пира ограничен примерно `MAX_BYTES × (KEEP + 1)`.
+
 ### Посмертная диагностика
 
 Причину смерти сессии (код выхода / сигнал) супервизор фиксирует в момент смерти в `exits.log` — это то, что обычная проверка «жив ли процесс» не ловит. Это материал для ответа на вопрос «почему агент умер».

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.83",
+  "version": "0.4.84",
   "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/launch/cmdlog.ts

@@ -1,69 +1,137 @@
-// Pane-log volume cap — tail-keep the per-identity pane-logs (<logDir>/<identity>.log), the RAW child
-// pty byte stream the supervisor appends for a session's whole life. Unlike the lifecycle/delivery logs
-// (their own size-rotation under logs/iapeer), the pane-log had NO bound and grew to hundreds of MB per
-// warm peer on an always-on host; the supervise tick caps it here. Best-effort BY CONSTRUCTION: a cap
-// must never fail a supervise tick — every export swallows FS errors.
+// Pane-log volume ROTATION — bound the per-identity pane-logs (<logDir>/<identity>.log),
+// the RAW child pty byte stream the supervisor appends for a session's whole life. Unlike
+// the daemon lifecycle/delivery/approvals logs (their own size+copies rotation under
+// logs/iapeer via storage/rotatelog.ts), the pane-log had NO bound and grew to tens of MB
+// per warm peer AND per always-on router on this host; the supervise tick rotates it here.
+//
+// MECHANISM — COPYTRUNCATE, not rename. The pane-log is written by a LONG-LIVED supervisor
+// holding a persistent O_APPEND fd (a different process from this daemon-side janitor), and
+// it is READ live by load-bearing consumers: telegram-runtime's occupancy signal keys on
+// the file's MTIME at its fixed path (canon: the pane-log occupancy contract), the boot
+// ready-gate seeds a headless xterm from the tail, doc's monitor tail -c's it. A rename
+// would move the writer's fd onto the rotated inode and briefly vanish the base path —
+// breaking mtime-occupancy. So rotation keeps the base INODE and PATH: it copies the base's
+// last maxBytes out to <path>.1 (shifting older copies up), then TRUNCATES the base in place
+// to its last tailBytes. Same inode ⇒ the supervisor's O_APPEND fd resumes at the new EOF
+// (proven by the live truncation test), mtime stays fresh, and the В19 heal never sees an
+// inode change (no spurious reopen). Readers keep reading the same path; the rotated copies
+// (<path>.1..N) are history nobody reads live.
+//
+// Best-effort BY CONSTRUCTION: rotation must never fail a supervise tick — every FS op
+// swallows errors. The dropped head of an already-oversized legacy file is redraw noise; the
+// last maxBytes is snapshotted, older bytes are discarded (never a giant copy of the bloat).
 
-import { openSync, closeSync, readSync, readdirSync, statSync, writeFileSync, fstatSync } from 'fs'
+import { openSync, closeSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync, fstatSync, renameSync } from 'fs'
 import { join } from 'path'
 
-/** Pane-log tail-keep cap (capPaneLogs): a per-identity pane-log over CAP is cut to
- *  its last KEEP. KEEP_BYTES INVARIANT — must stay ≥ the pane-log reader's seed
- *  window (readyGateModel SEED_BYTES = 4 MiB, the tail fed into the headless xterm
- *  for composer-occupancy / viewport detection); capping below it would starve that
- *  reader of the tail it reconstructs the live screen from. 8 MiB = 2× the seed. */
-export const PANELOG_CAP_BYTES = 32 * 1024 * 1024
-export const PANELOG_KEEP_BYTES = 8 * 1024 * 1024
+/** Rotate threshold (env IAPEER_PANELOG_MAX_BYTES) — a base pane-log over this is rotated.
+ *  Default 16 MiB (owner direction 12.07: order 10–20 MiB × 2–3 copies). */
+export const PANELOG_MAX_BYTES = 16 * 1024 * 1024
+/** Number of rotated copies kept (env IAPEER_PANELOG_KEEP) — <path>.1 (newest) … .N. Default 2. */
+export const PANELOG_COPIES = 2
+/** Base TAIL kept in place after a rotation. INVARIANT: ≥ the pane-log reader's seed window
+ *  (readyGateModel SEED_BYTES = 4 MiB, the tail fed into the headless xterm for
+ *  composer-occupancy / viewport). 8 MiB = 2× the seed. This is the reader-floor the base is
+ *  truncated to — NOT the copy count (that is IAPEER_PANELOG_KEEP). Internal invariant, not
+ *  env-tunable: capping the base below the seed would starve occupancy/ready-gate detection. */
+export const PANELOG_TAIL_BYTES = 8 * 1024 * 1024
 
-/** Tail-keep ONE file: if it exceeds capBytes, rewrite it as its last keepBytes.
- *  Safe against a live O_APPEND writer (the supervisor append-fd):
- *  the next write lands at the new EOF (proven by live truncation test). Lines
- *  appended between the tail-read and the rewrite are lost — acceptable mid-life
- *  noise. Returns true iff the file was capped. Best-effort: swallows FS errors. */
-function tailKeepFile(path: string, capBytes: number, keepBytes: number): boolean {
+/** Parse a positive integer env value, else the default (mirror of the daemon-log config helpers). */
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = raw !== undefined ? Number(raw) : NaN
+  return Number.isInteger(n) && n > 0 ? n : dflt
+}
+
+/** Resolve the pane-log rotation knobs from env (defaults above). maxBytes is floored just
+ *  above the reader-tail so the base can always drop below the threshold after a rotation
+ *  (else rotation would fire every tick). */
+export function paneLogRotateConfig(env: NodeJS.ProcessEnv = process.env): { maxBytes: number; copies: number } {
+  const maxBytes = Math.max(envPosInt(env.IAPEER_PANELOG_MAX_BYTES, PANELOG_MAX_BYTES), PANELOG_TAIL_BYTES + 1024 * 1024)
+  return { maxBytes, copies: envPosInt(env.IAPEER_PANELOG_KEEP, PANELOG_COPIES) }
+}
+
+/** Read the last wantBytes of a file into a Buffer (or null on error / absent). */
+function readTail(path: string, wantBytes: number): Buffer | null {
   try {
-    if (statSync(path).size <= capBytes) return false
     const fd = openSync(path, 'r')
-    let tail: Buffer
     try {
       const size = fstatSync(fd).size
-      const start = Math.max(0, size - keepBytes)
-      tail = Buffer.alloc(Math.min(keepBytes, size))
-      readSync(fd, tail, 0, tail.length, start)
+      const start = Math.max(0, size - wantBytes)
+      const buf = Buffer.alloc(Math.min(wantBytes, size))
+      if (buf.length > 0) readSync(fd, buf, 0, buf.length, start)
+      return buf
     } finally {
       closeSync(fd)
     }
+  } catch {
+    return null
+  }
+}
+
+/** Rotate ONE pane-log file if it exceeds maxBytes (copytruncate — see file header):
+ *   1. snapshot the base's last maxBytes (bounded — never a giant copy of legacy bloat)
+ *   2. shift .（k）→.（k+1）, dropping the oldest beyond `copies`; write the snapshot to .1
+ *   3. truncate the base IN PLACE to its last tailBytes (same inode: writer fd + mtime +
+ *      reader seed all survive; no В19 reopen)
+ *  Returns true iff rotated. Best-effort: swallows FS errors. */
+function rotateFile(path: string, maxBytes: number, copies: number, tailBytes: number): boolean {
+  try {
+    if (statSync(path).size <= maxBytes) return false
+    // 1 — snapshot the tail we promote to .1, taken BEFORE any truncate (copytruncate race:
+    //     bytes appended between here and the truncate are lost — accepted mid-life noise,
+    //     same as the pre-rotation tail-keep).
+    const rotBuf = readTail(path, maxBytes)
+    if (rotBuf === null || rotBuf.length === 0) return false
+    // 2 — shift existing copies up, dropping the oldest; also sweep one orphan beyond the
+    //     current copy count (handles a just-lowered IAPEER_PANELOG_KEEP).
+    try {
+      unlinkSync(`${path}.${copies + 1}`)
+    } catch {
+      /* absent → fine */
+    }
+    for (let k = copies - 1; k >= 1; k--) {
+      try {
+        renameSync(`${path}.${k}`, `${path}.${k + 1}`)
+      } catch {
+        /* absent → skip */
+      }
+    }
+    if (copies >= 1) writeFileSync(`${path}.1`, rotBuf, { mode: 0o600 })
+    // 3 — tail-keep the base in place (last tailBytes of the snapshot; same inode).
+    const tail = tailBytes >= rotBuf.length ? rotBuf : rotBuf.subarray(rotBuf.length - tailBytes)
     writeFileSync(path, tail, { mode: 0o600 })
     return true
   } catch {
-    return false // per-file best-effort
+    return false // per-file best-effort — a rotation never fails a supervise tick
   }
 }
 
-/** Tail-keep cap over the per-identity PANE-LOGS (<logDir>/<identity>.log) — the RAW
- *  TUI byte stream that pipe-pane (tmux) / the supervisor append for a session's whole
- *  life. Unlike the lifecycle/delivery logs (their own size-rotation under logs/iapeer),
- *  the pane-log had NO bound and grew to hundreds of MB per warm peer on an always-on
- *  host. The supervise tick caps it here with the same tail-keep mechanism as the
- *  cmd-logs. logDir (logs/lifecycle) holds ONLY pane-logs, so only top-level *.log is
- *  touched — never the rotated logs elsewhere. KEEP_BYTES stays ≥ the reader seed
- *  window (see PANELOG_KEEP_BYTES). Best-effort by construction. */
+/**
+ * Rotate the per-identity PANE-LOGS in logDir (logs/lifecycle). Scans top-level `*.log`
+ * only — the rotated copies are `<identity>.log.1..N` (do NOT end in `.log`), so they are
+ * never re-processed, and no other log lives here. Called each supervise tick (NOT H4-gated:
+ * log janitoring is orthogonal to lifecycle ownership, so launchd-managed routers' pane-logs
+ * are rotated too). maxBytes/copies come from paneLogRotateConfig(env). Best-effort by
+ * construction. Returns the rotated paths.
+ */
 export function capPaneLogs(
   logDir: string,
-  capBytes: number = PANELOG_CAP_BYTES,
-  keepBytes: number = PANELOG_KEEP_BYTES,
+  maxBytes: number = PANELOG_MAX_BYTES,
+  copies: number = PANELOG_COPIES,
+  tailBytes: number = PANELOG_TAIL_BYTES,
 ): string[] {
-  const capped: string[] = []
+  const cap = Math.max(maxBytes, tailBytes + 1024 * 1024) // base(tail) must be able to drop below cap
+  const rotated: string[] = []
   let names: string[]
   try {
     names = readdirSync(logDir)
   } catch {
-    return capped
+    return rotated
   }
   for (const name of names) {
-    if (!name.endsWith('.log')) continue
+    if (!name.endsWith('.log')) continue // skips the rotated <identity>.log.1/.2
     const path = join(logDir, name)
-    if (tailKeepFile(path, capBytes, keepBytes)) capped.push(path)
+    if (rotateFile(path, cap, copies, tailBytes)) rotated.push(path)
   }
-  return capped
+  return rotated
 }

package/src/lifecycle/index.ts

@@ -26,7 +26,7 @@ import {
 } from '../core/constants.ts'
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { err, ok, type Result } from '../core/errors.ts'
-import { capPaneLogs } from '../launch/cmdlog.ts'
+import { capPaneLogs, paneLogRotateConfig } from '../launch/cmdlog.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import { resolveMemoryWritableRoots } from '../status/index.ts'
 import { approvalModeOf, readPeerProfile, resolveIdentity, type ApprovalMode } from '../identity/index.ts'
@@ -1491,14 +1491,16 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
   const isAlive = deps.sessionAlive ?? ((sock: string, identity: string) => sessionAlive(sock, identity, env))
   const kill = deps.killSession ?? ((sock: string, identity: string) => killSession(sock, identity, env))
   const verbose = superviseLogVerbose(env)
-  // Pane-log volume cap (launch/cmdlog.ts capPaneLogs): the per-identity pane-log
+  // Pane-log volume ROTATION (launch/cmdlog.ts capPaneLogs): the per-identity pane-log
   // (<logDir>/<identity>.log) is the RAW TUI byte stream pipe-pane/the supervisor
-  // append for a session's whole life — it had NO bound and grew to hundreds of MB
-  // per warm peer on an always-on host. Tail-keep it each tick (KEEP ≥ the occupancy
-  // reader's 4 MiB seed window, so capping never starves composer detection).
-  // Not H4-gated: log janitoring is orthogonal to lifecycle ownership, so launchd-
-  // managed peers' pane-logs are capped too. Best-effort by construction.
-  capPaneLogs(cfg.logDir)
+  // append for a session's whole life — it had NO copies-rotation and grew to tens of MB
+  // per warm peer AND per always-on router on this host. Copytruncate-rotate it each tick
+  // (base kept in place — reader seed + telegram mtime-occupancy intact; last maxBytes
+  // snapshotted to <path>.1..N). Threshold/copies from IAPEER_PANELOG_MAX_BYTES /
+  // IAPEER_PANELOG_KEEP (defaults 16 MiB × 2). Not H4-gated: log janitoring is orthogonal
+  // to lifecycle ownership, so launchd-managed routers' pane-logs are rotated too.
+  const paneLogRc = paneLogRotateConfig(env)
+  capPaneLogs(cfg.logDir, paneLogRc.maxBytes, paneLogRc.copies)
   // Durable decision trace (eventlog.ts): every reap/death/eager-fresh gets a line
   // so a postmortem can answer "when & how did peer X's prior session end" even
   // after the .idle-reaped / .deaths markers are consumed. alive / skipped-launchd