@agfpd/iapeer 0.4.105 → 0.4.106

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

@@ -63,6 +63,8 @@ The daemon's supervisory tick is fixed — once a minute, not configurable.
 | `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_PANELOG_DIR_BUDGET` | `512 MiB` | The retention ceiling on the WHOLE `logs/lifecycle/` directory — the bound that does not grow with the fleet. |
+| `IAPEER_PANELOG_STALE_DAYS` | `14` | Age after which a pane-log artifact (base or copy) is reclaimed — this is what frees the logs of dead/removed peers. |
 | `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. |
 
@@ -84,6 +86,14 @@ The daemon keeps three durable logs in `~/.iapeer/logs/iapeer/`:
 
 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)`.
 
+That per-file bound alone is a *per-peer* one, so the directory total was still a product of the fleet size (peers × runtimes) and nothing ever reclaimed the artifacts of a peer that had died or been removed. The same supervise tick therefore also runs a **retention** pass over the directory, reclaiming in cheapest-loss-first order:
+
+1. **Age** — every artifact (base or copy) untouched for longer than `IAPEER_PANELOG_STALE_DAYS` (14 d) is deleted. Nothing live reads a base that cold — idle-reap ends a warm session in minutes, and only a *current* session's base feeds the ready-gate seed and the mtime-occupancy signal — so this is what finally frees dead, removed, and renamed peers. The supervisor recreates the file on the next wake.
+2. **Budget / copies** — while the directory exceeds `IAPEER_PANELOG_DIR_BUDGET` (512 MiB), rotated copies are deleted oldest-first. They are history nobody reads live, so they are the correct first casualty.
+3. **Budget / backstop** — if the copies run out and the directory is still over budget, the largest bases are shrunk in place to the 8 MiB reader-floor, inode *and mtime* preserved (a janitor write must never masquerade as peer activity in the occupancy contract).
+
+The floor of step 3 is `live-identities × 8 MiB`, so the budget is authoritative up to roughly 64 concurrently warm identities at the defaults; past that the reader-floor deliberately outranks the budget (truncating below the seed window would starve occupancy/ready-gate detection) and the pass records `outcome=over-budget-after-gc` in `lifecycle.log`, where raising `IAPEER_PANELOG_DIR_BUDGET` is the remedy. Every pass that reclaims anything leaves an `action=panelog-gc` line with the before/after megabytes. The whole pass is idempotent and best-effort by construction: it runs on each tick and never fails one.
+
 ### 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

@@ -63,6 +63,8 @@
 | `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_PANELOG_DIR_BUDGET` | `512 МиБ` | Потолок хранения для ВСЕГО каталога `logs/lifecycle/` — граница, которая не растёт вместе с флотом. |
+| `IAPEER_PANELOG_STALE_DAYS` | `14` | Возраст, после которого артефакт pane-лога (база или копия) освобождается; именно это убирает логи мёртвых и удалённых пиров. |
 | `IAPEER_SUPERVISE_LOG_VERBOSE` | выкл. | Подробный лог надзорных тиков (по умолчанию пишутся только решения, не рутинные «ничего не делаю»). |
 | `IAPEER_DAEMON_LOG` | выкл. | Расширенный лог демона. |
 
@@ -84,6 +86,14 @@
 
 Пер-пировые **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)`.
 
+Эта пер-файловая граница действует лишь *на одного пира*, поэтому суммарный вес каталога оставался произведением размера флота (пиры × рантаймы), а артефакты умершего или удалённого пира не освобождались никогда. Поэтому тот же надзорный тик выполняет над каталогом проход **хранения (retention)**, освобождая место в порядке «сначала наименее ценное»:
+
+1. **Возраст** — любой артефакт (база или копия), не тронутый дольше `IAPEER_PANELOG_STALE_DAYS` (14 сут.), удаляется. Настолько холодную базу не читает ничто живое: idle-reap завершает тёплую сессию за минуты, а seed boot-гейта и сигнал занятости по mtime смотрят только на базу *текущей* сессии. Именно этот ярус освобождает мёртвых, удалённых и переименованных пиров; при следующем пробуждении супервизор создаёт файл заново.
+2. **Бюджет / копии** — пока каталог превышает `IAPEER_PANELOG_DIR_BUDGET` (512 МиБ), ротированные копии удаляются начиная с самых старых. Это история, которую никто не читает живьём, — верная первая жертва.
+3. **Бюджет / страховка** — если копии кончились, а каталог всё ещё сверх бюджета, крупнейшие базы усекаются на месте до читательского пола в 8 МиБ с сохранением inode *и mtime* (запись уборщика не должна выдавать себя за активность пира в контракте занятости).
+
+Пол яруса 3 равен `живые_идентичности × 8 МиБ`, поэтому на умолчаниях бюджет авторитетен примерно до 64 одновременно тёплых идентичностей; дальше читательский пол намеренно перевешивает бюджет (усечение ниже seed-окна лишило бы детект занятости и boot-гейт данных), проход пишет в `lifecycle.log` строку с `outcome=over-budget-after-gc`, и лечится это повышением `IAPEER_PANELOG_DIR_BUDGET`. Каждый проход, что-либо освободивший, оставляет строку `action=panelog-gc` с мегабайтами до и после. Проход идемпотентен и best-effort по построению: выполняется на каждом тике и никогда его не роняет.
+
 ### Посмертная диагностика
 
 Причину смерти сессии (код выхода / сигнал) супервизор фиксирует в момент смерти в `exits.log` — это то, что обычная проверка «жив ли процесс» не ловит. Это материал для ответа на вопрос «почему агент умер».

package/package.json

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

@@ -21,7 +21,24 @@
 // 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, unlinkSync, writeFileSync, fstatSync, renameSync } from 'fs'
+// VOLUME RETENTION (gcPaneLogs, below) is the SECOND half of the bound. Per-file rotation caps one
+// identity (16 MiB base + N×16 MiB copies), but the DIRECTORY total is then a product of the fleet
+// size — it only ever grows with peers × runtimes, and nothing ever reclaimed the artifacts of a peer
+// that died or was removed months ago. The janitor therefore also enforces an age retention and a
+// hard directory BUDGET each tick, so the ceiling is a fixed number instead of a per-peer multiple.
+
+import {
+  openSync,
+  closeSync,
+  readSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+  fstatSync,
+  renameSync,
+  utimesSync,
+} from 'fs'
 import { join } from 'path'
 
 /** Rotate threshold (env IAPEER_PANELOG_MAX_BYTES) — a base pane-log over this is rotated.
@@ -36,6 +53,17 @@ export const PANELOG_COPIES = 2
  *  env-tunable: capping the base below the seed would starve occupancy/ready-gate detection. */
 export const PANELOG_TAIL_BYTES = 8 * 1024 * 1024
 
+/** Directory BUDGET (env IAPEER_PANELOG_DIR_BUDGET) — the observable ceiling on the WHOLE
+ *  pane-log dir, enforced every tick by gcPaneLogs. Default 512 MiB. Sized off the live shape of
+ *  this host: the artifacts that are load-bearing are the bases of CONCURRENTLY warm sessions
+ *  (~12 × ≤16 MiB here), everything else is history. See gcPaneLogs for the honest boundary. */
+export const PANELOG_DIR_BUDGET_BYTES = 512 * 1024 * 1024
+/** Age retention (env IAPEER_PANELOG_STALE_DAYS) — any pane-log artifact untouched for longer is
+ *  reclaimed. Default 14 d: FAR beyond any live signal (idle-reap kills a warm session in minutes,
+ *  the ready-gate seed and the mtime-occupancy contract only ever read a CURRENT session's base),
+ *  so a base this cold belongs to a peer that is dead, removed, or renamed. A wake recreates it. */
+export const PANELOG_STALE_MS = 14 * 24 * 60 * 60 * 1000
+
 /** 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
@@ -135,3 +163,164 @@ export function capPaneLogs(
   }
   return rotated
 }
+
+// ─────────────────────────── volume retention (dir budget) ───────────────────────────
+
+/** Resolve the retention knobs from env (defaults above). */
+export function paneLogGcConfig(env: NodeJS.ProcessEnv = process.env): { budgetBytes: number; staleMs: number } {
+  const days = env.IAPEER_PANELOG_STALE_DAYS
+  const staleDays = days !== undefined && Number.isFinite(Number(days)) && Number(days) > 0 ? Number(days) : 14
+  return {
+    budgetBytes: envPosInt(env.IAPEER_PANELOG_DIR_BUDGET, PANELOG_DIR_BUDGET_BYTES),
+    staleMs: Math.round(staleDays * 24 * 60 * 60 * 1000),
+  }
+}
+
+/** One pane-log artifact on disk. `base` = `<identity>.log` (live-readable), else a rotated copy. */
+type PaneLogArtifact = { path: string; size: number; mtimeMs: number; base: boolean }
+
+/** Snapshot the dir's artifacts (bases + rotated copies). Unreadable entries are skipped. */
+function scanPaneLogs(logDir: string): PaneLogArtifact[] {
+  let names: string[]
+  try {
+    names = readdirSync(logDir)
+  } catch {
+    return []
+  }
+  const out: PaneLogArtifact[] = []
+  for (const name of names) {
+    const base = name.endsWith('.log')
+    if (!base && !/\.log\.\d+$/.test(name)) continue // only OUR artifacts — never a foreign file
+    const path = join(logDir, name)
+    try {
+      const st = statSync(path)
+      if (st.isFile()) out.push({ path, size: st.size, mtimeMs: st.mtimeMs, base })
+    } catch {
+      /* vanished mid-scan → fine */
+    }
+  }
+  return out
+}
+
+/** Truncate a base IN PLACE to its last tailBytes, PRESERVING its mtime. Same inode (writer's
+ *  O_APPEND fd + В19 heal survive, exactly as rotateFile step 3), and the mtime restore keeps the
+ *  pane-log OCCUPANCY contract honest: a janitor write must never masquerade as peer activity.
+ *  Returns the bytes reclaimed (0 on no-op/error). */
+function shrinkBase(path: string, tailBytes: number): number {
+  try {
+    const st = statSync(path)
+    if (st.size <= tailBytes) return 0
+    const tail = readTail(path, tailBytes)
+    if (tail === null) return 0
+    writeFileSync(path, tail, { mode: 0o600 })
+    try {
+      utimesSync(path, st.atime, st.mtime) // janitor ≠ activity
+    } catch {
+      /* best-effort */
+    }
+    return st.size - tail.length
+  } catch {
+    return 0
+  }
+}
+
+/** What one GC pass did — observability for the supervise-tick trace. */
+export type PaneLogGcResult = {
+  bytesBefore: number
+  bytesAfter: number
+  /** Artifacts deleted by the AGE retention (dead/removed peers, ancient rotations). */
+  reapedStale: number
+  /** Rotated copies deleted by the BUDGET, oldest first. */
+  droppedCopies: number
+  /** Live bases shrunk to the reader-floor as the budget backstop. */
+  shrunkBases: number
+  /** True when even the backstop could not reach the budget — see the honest boundary below. */
+  overBudget: boolean
+}
+
+/**
+ * RETENTION pass over the pane-log dir — turns the per-file rotation bound into a DIRECTORY bound.
+ * Runs right after capPaneLogs on every supervise tick (idempotent, best-effort, no manual step),
+ * reclaiming in cheapest-loss-first order:
+ *
+ *   1. AGE — every artifact (base OR copy) untouched for > staleMs is deleted. This is what finally
+ *      reclaims peers that died, were removed, or renamed: nothing live reads a base that cold, and
+ *      the supervisor recreates it on the next wake.
+ *   2. BUDGET / copies — while the dir exceeds budgetBytes, delete rotated copies OLDEST FIRST.
+ *      Copies are history nobody reads live, so they are the correct first casualty.
+ *   3. BUDGET / backstop — if copies ran out and the dir is STILL over, shrink the largest bases to
+ *      the reader-floor (tailBytes, ≥ the ready-gate seed window) with mtime preserved.
+ *
+ * HONEST BOUNDARY: the floor of step 3 is `live-identities × tailBytes` (8 MiB each). The budget is
+ * therefore authoritative up to ~`budgetBytes / tailBytes` concurrently warm identities (~64 at the
+ * defaults); beyond that the reader-floor wins, `overBudget` comes back true, and the budget must be
+ * raised via IAPEER_PANELOG_DIR_BUDGET. Truncating below the seed window would starve
+ * occupancy/ready-gate detection, so the floor deliberately outranks the budget.
+ */
+export function gcPaneLogs(
+  logDir: string,
+  opts: { budgetBytes?: number; staleMs?: number; tailBytes?: number; nowMs?: number } = {},
+): PaneLogGcResult {
+  const budgetBytes = opts.budgetBytes ?? PANELOG_DIR_BUDGET_BYTES
+  const staleMs = opts.staleMs ?? PANELOG_STALE_MS
+  const tailBytes = opts.tailBytes ?? PANELOG_TAIL_BYTES
+  const nowMs = opts.nowMs ?? Date.now()
+
+  let live = scanPaneLogs(logDir)
+  const bytesBefore = live.reduce((s, a) => s + a.size, 0)
+  const res: PaneLogGcResult = {
+    bytesBefore,
+    bytesAfter: bytesBefore,
+    reapedStale: 0,
+    droppedCopies: 0,
+    shrunkBases: 0,
+    overBudget: false,
+  }
+  if (live.length === 0) return res
+
+  let total = bytesBefore
+  const drop = (a: PaneLogArtifact): boolean => {
+    try {
+      unlinkSync(a.path)
+      total -= a.size
+      return true
+    } catch {
+      return false // per-file best-effort — retention never fails a supervise tick
+    }
+  }
+
+  // 1 — AGE retention.
+  const staleCutoff = nowMs - staleMs
+  const kept: PaneLogArtifact[] = []
+  for (const a of live) {
+    if (a.mtimeMs < staleCutoff && drop(a)) res.reapedStale++
+    else kept.push(a)
+  }
+  live = kept
+
+  // 2 — BUDGET: rotated copies, oldest first.
+  if (total > budgetBytes) {
+    const copies = live.filter((a) => !a.base).sort((x, y) => x.mtimeMs - y.mtimeMs)
+    for (const a of copies) {
+      if (total <= budgetBytes) break
+      if (drop(a)) res.droppedCopies++
+    }
+  }
+
+  // 3 — BUDGET backstop: shrink the largest bases to the reader-floor.
+  if (total > budgetBytes) {
+    const bases = live.filter((a) => a.base && a.size > tailBytes).sort((x, y) => y.size - x.size)
+    for (const a of bases) {
+      if (total <= budgetBytes) break
+      const freed = shrinkBase(a.path, tailBytes)
+      if (freed > 0) {
+        total -= freed
+        res.shrunkBases++
+      }
+    }
+  }
+
+  res.bytesAfter = total
+  res.overBudget = total > budgetBytes
+  return res
+}

package/src/lifecycle/index.ts

@@ -28,7 +28,7 @@ import {
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { renderEnvelopeForAgent } from '../codec/index.ts'
 import { err, ok, type Result } from '../core/errors.ts'
-import { capPaneLogs, paneLogRotateConfig } from '../launch/cmdlog.ts'
+import { capPaneLogs, gcPaneLogs, paneLogGcConfig, 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'
@@ -1524,12 +1524,31 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
   // to lifecycle ownership, so launchd-managed routers' pane-logs are rotated too.
   const paneLogRc = paneLogRotateConfig(env)
   capPaneLogs(cfg.logDir, paneLogRc.maxBytes, paneLogRc.copies)
+  // Pane-log volume RETENTION (gcPaneLogs): rotation bounds ONE identity, but the DIRECTORY total
+  // is that bound × the fleet — it only grew with peers × runtimes, and the artifacts of dead /
+  // removed peers were never reclaimed. Enforce the age retention + the directory BUDGET right
+  // after the rotation, on the same tick and the same best-effort contract (knobs:
+  // IAPEER_PANELOG_DIR_BUDGET / IAPEER_PANELOG_STALE_DAYS, defaults 512 MiB / 14 d).
+  const paneLogGc = gcPaneLogs(cfg.logDir, { ...paneLogGcConfig(env), nowMs })
   // 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
   // are steady-state non-decisions → logged only under IAPEER_SUPERVISE_LOG_VERBOSE.
   const trace = (fields: Record<string, string | number | undefined>): void =>
     appendLifecycleEvent(cfg.eventLogDir, { ev: 'supervise', ...fields }, { env, nowMs })
+  // Retention is silent in steady state (nothing to reclaim); a pass that actually reclaimed —
+  // or that could NOT reach the budget even after the backstop — leaves a durable line.
+  if (paneLogGc.reapedStale || paneLogGc.droppedCopies || paneLogGc.shrunkBases || paneLogGc.overBudget) {
+    trace({
+      action: 'panelog-gc',
+      stale: paneLogGc.reapedStale,
+      copies: paneLogGc.droppedCopies,
+      shrunk: paneLogGc.shrunkBases,
+      mb_before: Math.round(paneLogGc.bytesBefore / (1024 * 1024)),
+      mb_after: Math.round(paneLogGc.bytesAfter / (1024 * 1024)),
+      outcome: paneLogGc.overBudget ? 'over-budget-after-gc' : 'within-budget',
+    })
+  }
   const out: SuperviseOutcome[] = []
   const ctx: SuperviseCtx = { cfg, env, nowMs, lastTurnMt, childActivityMt, isAlive, kill, verbose, trace }
   for (const s of readSessionStates(cfg)) {