arisa 5.1.68 → 5.2.17

package/README.md

@@ -108,13 +108,16 @@ Per chat (`~/.arisa/chats/<chatId>/`):
 - chat-scoped daemon infrastructure lives in `state/tools/<tool>/daemon/`; persistent tool data stays beside it
 - ephemeral scratch lives under `tmp/`
 
-Managed daemons become ready only after their tool-defined health operation succeeds through the normal command queue. Arisa records heartbeats, successful jobs, errors, and standard lifecycle states, then retries recovery or recreates an unhealthy process with its persisted scope and startup context.
+Managed daemons become ready only after their tool-defined health operation succeeds through the normal command queue. Arisa records heartbeats, successful jobs, errors, and standard lifecycle states, then retries recovery or recreates an unhealthy process with its persisted scope and startup context. The supervisor automatically removes registrations and daemon runtime directories that no longer match an installed daemon tool. A live process is terminated only when its command line matches the registered entry and daemon invocation; unverifiable PIDs are left untouched and reported for attention.
 
 Daemon tools may opt into the `arisa-daemon-v1` local protocol for immediate
 multiplexed jobs and incremental NDJSON events over a capability-protected local
 socket. The runtime persists request, accepted and terminal records so a restart
-can recover queued work and will not silently repeat an accepted effect. Legacy
-daemon tools continue to use the existing request-file contract.
+can recover queued work and will not silently repeat an accepted effect. When a
+client deadline expires, the runtime sends a scoped cancellation signal to that
+job before closing the request; cooperative tools can stop it without restarting
+the shared daemon or interrupting unrelated sessions. Legacy daemon tools
+continue to use the existing request-file contract.
 
 ### Arisa Master and Slave
 
@@ -148,12 +151,31 @@ Automatic context compaction uses Pi's native implementation and can be tuned in
       "enabled": true,
       "reserveTokens": 120000,
       "keepRecentTokens": 20000
+    },
+    "sessionRotation": {
+      "enabled": true,
+      "compactAtPersistedBytes": 25165824,
+      "maxPersistedBytes": 33554432
+    },
+    "toolFanout": {
+      "enabled": true,
+      "maxConcurrent": 2,
+      "pressureConcurrent": 1,
+      "serializePercent": 60
+    },
+    "turnCoordinator": {
+      "enabled": true,
+      "backgroundQueueTtlMs": 600000,
+      "interactiveQueueTtlMs": 0,
+      "maxQueued": 100
     }
   }
 }
 ```
 
-Pi compacts when the context exceeds the model's context window minus `reserveTokens`. The default keeps a large reserve so compaction occurs before Arisa Doctor's context warning on the default model. Set a smaller reserve when using models with substantially smaller context windows. Arisa does not add Telegram commands or compaction notifications.
+Pi compacts when the context exceeds the model's context window minus `reserveTokens`. Arisa also requests compaction when persisted history exceeds `compactAtPersistedBytes`, then rotates to a fresh JSONL using the latest summary and retained active context. Before Pi loads a recent session above `maxPersistedBytes`, Arisa discovers the last valid active-branch compaction by streaming, atomically creates a compact child with `parentSession`, and leaves the historical JSONL intact. An unsafe oversized session is rejected rather than loaded into an OOM-prone worker. Same-turn `run_tool` fan-out is capped at two, becomes sequential when heap usage reaches `serializePercent`, and uses the heap circuit breaker before every admission. Across chats and topics, `turnCoordinator` admits only one Pi turn or headless poll at a time, prioritizes interactive messages and events over queued background work, and safely expires stale background admissions before execution. Set a smaller token reserve when using models with substantially smaller context windows. Arisa adds no Telegram commands or compaction notifications.
+
+Browser and checkout tools report lifecycle states separately: profile connection is not a session share, a session share is not target validation, wallet enrollment is not checkout submission, and only explicit target or merchant evidence can confirm the final objective.
 
 ## Install globally
 
@@ -181,9 +203,9 @@ arisa --silent           # run without verbose logs
 
 Authorized Telegram chats can run the same safe service lifecycle with `/restart`.
 
-Background mode runs the Telegram/Pi worker under a lightweight supervisor. Unexpected worker exits use bounded exponential restart backoff. Scheduled agent tasks are serialized FIFO per conversation while different conversations remain independent; execution deadlines default to 15 minutes for scheduled prompts and 5 minutes for agent events. A timed-out turn is marked outcome-uncertain and is never replayed automatically. These policies can be overridden with `service.workerRestart*` and `tasks.*TimeoutMs` in the Arisa config.
+Background mode runs the Telegram/Pi worker under a lightweight supervisor. Unexpected worker exits use bounded exponential restart backoff. After recovery, authorized Telegram chats automatically receive a bounded report with the classified exit cause, recent tool names and counts, uncertain scheduled executions, restart delay, and running version; prompts and private payloads are never included. Scheduled agent tasks are serialized FIFO per conversation while different conversations remain independent; execution deadlines default to 15 minutes for scheduled prompts and 5 minutes for agent events. A timed-out turn is marked outcome-uncertain and is never replayed automatically. These policies can be overridden with `service.workerRestart*` and `tasks.*TimeoutMs` in the Arisa config.
 
-Tools may declare weighted execution resources in their manifest, for example `"execution": { "resourceClass": "browser", "weight": 1 }`. Runs sharing a declared class queue fairly once they reach its capacity; undeclared lightweight tools remain unconstrained. The default capacity is two per declared class, while the built-in `orchestrator` class has capacity one. An opt-in tool may set `deduplicateConcurrent: true` to join only exact concurrent duplicates from the same chat; later or different requests still execute normally. Override capacities with `toolExecution.defaultCapacity`, `toolExecution.capacities`, and `toolExecution.maxQueuedPerClass`. Arisa logs queue waits, joined duplicates, and new worker RSS peaks for operational measurement.
+Tools may opt into weighted resource governance with a manifest declaration such as `"execution": { "resourceClass": "browser", "weight": 1 }`; undeclared lightweight and nested orchestration calls remain unconstrained. Declared runs queue when their class reaches its concurrency capacity. A global memory broker also reserves RAM across declared classes, leaving configurable system and core reserves before it admits work. The broker starts declared tools with a 384 MiB recommendation, derives their V8 heap from the granted memory, and raises the recommendation after an isolated memory-limit failure. Manifest values for `maxHeapMb` and `maxMemoryMb` act as ceilings; `maxOutputBytes` bounds protocol output. On systemd-based Linux hosts, each declared process tree runs in `arisa-tools.slice` with `MemoryHigh`, `MemoryMax`, bounded swap, and a higher OOM-kill priority than the core. Tool daemons receive the same OOM priority. Arisa lowers the core OOM score when the service account permits it. A limit failure stays inside the tool process tree and returns an uncertain result. Set host reserves and dynamic grants with `toolExecution.systemReserveMb`, `coreReserveMb`, `initialToolMemoryMb`, `minimumToolMemoryMb`, and `maximumToolMemoryMb`. Heap, soft-pressure, and swap controls use `toolHeapPercent`, `toolMemoryHighPercent`, and `toolSwapMaxMb`. Admission still checks `maxWorkerRssMb` and `maxSwapUsedPercent`. Class controls remain available through `defaultCapacity`, `capacities`, and `maxQueuedPerClass`. `deduplicateConcurrent: true` joins exact concurrent duplicates from the same chat.
 
 Runtime model override (current process only):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "5.1.68",
+  "version": "5.2.17",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",

package/src/core/agent/agent-manager.js

@@ -8,11 +8,15 @@ import { buildPiToolPolicy } from "./core-tools.js";
 import { createSystemShellTool } from "./system-shell-tool.js";
 import { clampModelThinkingLevel } from "./pi-runtime.js";
 import { clampModelSpeed, createModelSpeedController } from "./model-speed.js";
-import { arisaHomeDir } from "../../runtime/paths.js";
+import { arisaHomeDir } from "../../platform/paths.js";
 import { AgentSessionLifecycle } from "./agent-session-lifecycle.js";
 import { createPiCapabilityTools } from "./pi-capability-tools.js";
 import { ToolResourceNoteStore } from "../tools/tool-resource-note-store.js";
 import { materializeToolOutput } from "../tools/tool-output-materializer.js";
+import { WorkerHeapCircuitBreaker } from "./worker-heap-circuit-breaker.js";
+import { WorkerToolFanoutController } from "./worker-tool-fanout.js";
+import { compactionRotationRequest, normalizeSessionRotationPolicy } from "./session-rotation.js";
+import { AgentTurnCoordinator } from "./agent-turn-coordinator.js";
 
 const piValidationTimeoutMs = 60_000;
 const arisaToolNames = [
@@ -154,7 +158,23 @@ export class AgentManager {
     this.resourceNotes = new ToolResourceNoteStore();
     this.sessionLifecycle = new AgentSessionLifecycle({
       logger,
-      summarizeContext: summarizeRetainedContext
+      summarizeContext: summarizeRetainedContext,
+      cachePolicy: config.pi.sessionCache,
+      sessionRotationPolicy: config.pi.sessionRotation
+    });
+    this.heapCircuitBreaker = new WorkerHeapCircuitBreaker({
+      lifecycle: this.sessionLifecycle,
+      logger,
+      config: config.pi.heapCircuitBreaker
+    });
+    this.toolFanout = new WorkerToolFanoutController({
+      heapCircuitBreaker: this.heapCircuitBreaker,
+      logger,
+      config: config.pi.toolFanout
+    });
+    this.turnCoordinator = new AgentTurnCoordinator({
+      logger,
+      config: config.pi.turnCoordinator
     });
     this.sessions = this.sessionLifecycle.sessions;
     this.pendingNewSessions = this.sessionLifecycle.pendingNewSessions;
@@ -188,6 +208,11 @@ export class AgentManager {
 
   setConfig(config) {
     this.sessionLifecycle.resetConfigState();
+    this.sessionLifecycle.setCachePolicy(config.pi.sessionCache);
+    this.sessionLifecycle.setSessionRotationPolicy(config.pi.sessionRotation);
+    this.heapCircuitBreaker.setConfig(config.pi.heapCircuitBreaker);
+    this.toolFanout.setConfig(config.pi.toolFanout);
+    this.turnCoordinator.setConfig(config.pi.turnCoordinator);
     this.config = config;
   }
 
@@ -209,14 +234,93 @@ export class AgentManager {
     }
   }
 
-  getRuntimeDiagnostic() {
-    return this.sessionLifecycle.getDiagnostic();
+  async getRuntimeDiagnostic() {
+    const diagnostic = await this.sessionLifecycle.getDiagnostic();
+    return {
+      ...diagnostic,
+      heapCircuitBreaker: this.heapCircuitBreaker.getDiagnostic(),
+      toolFanout: this.toolFanout.getDiagnostic(),
+      turnCoordinator: this.turnCoordinator.diagnostic()
+    };
   }
 
   createSessionManager(chatId, workspaceDir = arisaInstallDir, sessionRevision = 0) {
     return this.sessionLifecycle.createSessionManager(chatId, workspaceDir, sessionRevision);
   }
 
+  async estimatePersistedSessionBytes(session) {
+    const sessionStats = session?.getSessionStats?.();
+    const sessionFile = session?.sessionManager?.getSessionFile?.() || sessionStats?.sessionFile;
+    if (!sessionFile) return 0;
+    try {
+      return (await stat(sessionFile)).size;
+    } catch {
+      return 0;
+    }
+  }
+
+  async acquireSessionContext(sessionKey, context) {
+    const persistedBytes = await this.estimatePersistedSessionBytes(context.session);
+    this.sessionLifecycle.acquireCached(sessionKey, persistedBytes);
+    context.release = () => this.releaseSessionContext(sessionKey, context);
+    await this.sessionLifecycle.enforceCachePolicy({ protectedSessionKeys: [sessionKey] });
+    return context;
+  }
+
+  async compactPersistedSessionIfNeeded(sessionKey, context, persistedBytes) {
+    const policy = normalizeSessionRotationPolicy(this.config.pi.sessionRotation);
+    if (!policy.enabled
+      || persistedBytes <= policy.compactAtPersistedBytes
+      || context.rotationRequest
+      || typeof context.session?.compact !== "function") return;
+    try {
+      this.logger?.log("agent", `compacting ${Math.ceil(persistedBytes / 1024 / 1024)} MiB Pi session for chat ${sessionKey} before rotation`);
+      await context.session.compact();
+      await context.rotationCheckPromise;
+    } catch (error) {
+      this.logger?.error?.("agent", `persisted-size compaction failed for chat ${sessionKey}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async releaseSessionContext(sessionKey, context) {
+    if (this.sessions.get(String(sessionKey)) !== context) return;
+    await context.rotationCheckPromise;
+    const persistedBytes = await this.estimatePersistedSessionBytes(context.session);
+    if ((context.activeUsers || 0) <= 1) {
+      await this.compactPersistedSessionIfNeeded(sessionKey, context, persistedBytes);
+    }
+    this.sessionLifecycle.releaseCached(sessionKey, persistedBytes);
+    if ((context.activeUsers || 0) === 0 && context.rotationRequest) {
+      const request = context.rotationRequest;
+      const parentSession = context.session.sessionFile || "";
+      this.logger?.log("agent", `rotating ${Math.ceil(request.persistedBytes / 1024 / 1024)} MiB Pi session for chat ${sessionKey} after compaction`);
+      this.sessionLifecycle.resetSession(sessionKey, {
+        handoff: request.handoff,
+        parentSession,
+        source: "compaction-rotation"
+      });
+      await this.sessionLifecycle.waitForClose(sessionKey);
+      return;
+    }
+    await this.sessionLifecycle.enforceCachePolicy();
+  }
+
+  scheduleCompactionRotationCheck(sessionKey, context, event) {
+    if (event?.type !== "compaction_end") return;
+    const previous = context.rotationCheckPromise || Promise.resolve();
+    context.rotationCheckPromise = previous
+      .catch(() => {})
+      .then(async () => {
+        if (this.sessions.get(String(sessionKey)) !== context) return;
+        const persistedBytes = await this.estimatePersistedSessionBytes(context.session);
+        const request = compactionRotationRequest(event, persistedBytes, this.config.pi.sessionRotation);
+        if (request) context.rotationRequest = request;
+      })
+      .catch((error) => {
+        this.logger?.error?.("agent", `session rotation check failed for chat ${sessionKey}: ${error instanceof Error ? error.message : String(error)}`);
+      });
+  }
+
   async validatePiAgent(config = this.config) {
     this.logger?.log("agent", "validating Pi session");
     const { authStorage, modelRegistry } = createPiRuntime({
@@ -254,6 +358,7 @@ export class AgentManager {
   }
 
   async getSessionContext(chatId, telegram, { scopeChatId = chatId, accessGuard = async () => {} } = {}) {
+    await this.heapCircuitBreaker.admit();
     const sessionKey = String(chatId);
     const modelSelection = resolveChatModelSelection(this.config, sessionKey);
     const effectiveModelId = modelSelection.model;
@@ -274,7 +379,7 @@ export class AgentManager {
         existing.telegramTarget.current = telegram;
         existing.accessGuardTarget.current = accessGuard;
         this.logger?.log("agent", `reusing session for chat ${sessionKey}`);
-        return existing;
+        return this.acquireSessionContext(sessionKey, existing);
       }
       this.logger?.log("agent", `model changed for chat ${sessionKey}: ${existing?.modelKey || "unknown"} -> ${effectiveModelKey}; recreating session`);
       this.closeCachedSession(sessionKey);
@@ -362,11 +467,14 @@ export class AgentManager {
       modelKey: effectiveModelKey,
       speedController,
       telegramTarget,
-      accessGuardTarget
+      accessGuardTarget,
+      rotationCheckPromise: Promise.resolve(),
+      rotationRequest: null
     };
+    session.subscribe((event) => this.scheduleCompactionRotationCheck(sessionKey, ctx, event));
     this.sessions.set(sessionKey, ctx);
     if (isNewSession) this.sessionLifecycle.completeNewSession(sessionKey);
-    return ctx;
+    return this.acquireSessionContext(sessionKey, ctx);
   }
 
   async getAvailableModels(chatId) {
@@ -384,9 +492,15 @@ export class AgentManager {
   }
 
   async close() {
+    this.turnCoordinator.close();
     await this.sessionLifecycle.closeAll();
   }
 
+  async runTurn(options, work) {
+    if (typeof work !== "function") throw new Error("Agent turn work is required");
+    return this.turnCoordinator.run(options, work);
+  }
+
   async runTool({ name, request, chatId, taskContext = null }) {
     await this.toolRegistry.load();
     this.logger?.log("agent", `run_tool ${name}`);
@@ -413,7 +527,8 @@ export class AgentManager {
       telegram,
       chatId,
       policy,
-      logger: this.logger
+      logger: this.logger,
+      toolFanout: this.toolFanout
     });
   }
 

package/src/core/agent/agent-session-lifecycle.js

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { getChatPiSessionsDir, sessionStartOperationalNotesFile } from "../../runtime/paths.js";
+import { getChatPiSessionsDir, sessionStartOperationalNotesFile } from "../../platform/paths.js";
 import { arisaInstallDir } from "./runtime-context.js";
+import { migrateRecentSessionBeforeLoad } from "./session-preload-migration.js";
 
 const operationalNoteMaxChars = 220;
 
@@ -26,7 +27,7 @@ export function loadSessionStartOperationalNotes() {
   }
 }
 
-function formatSessionStartOperationalNotes(notes) {
+export function formatSessionStartOperationalNotes(notes) {
   if (!notes.length) return "";
   return [
     "Durable operating notes for this Arisa session:",
@@ -41,13 +42,89 @@ function closeAgentSession(session) {
 }
 
 export class AgentSessionLifecycle {
-  constructor({ logger, summarizeContext }) {
+  constructor({ logger, summarizeContext, cachePolicy = {}, sessionRotationPolicy = {} }) {
     this.logger = logger;
     this.summarizeContext = summarizeContext;
     this.sessions = new Map();
     this.pendingNewSessions = new Set();
     this.pendingSessionHandoffs = new Map();
     this.sessionClosePromises = new Map();
+    this.setCachePolicy(cachePolicy);
+    this.setSessionRotationPolicy(sessionRotationPolicy);
+  }
+
+  setCachePolicy(cachePolicy = {}) {
+    this.cachePolicy = {
+      maxSessions: Math.max(1, Number(cachePolicy.maxSessions) || 3),
+      maxPersistedBytes: Math.max(1, Number(cachePolicy.maxPersistedBytes) || 48 * 1024 * 1024)
+    };
+  }
+
+  setSessionRotationPolicy(policy = {}) {
+    this.sessionRotationPolicy = { ...policy };
+  }
+
+  acquireCached(sessionKey, persistedBytes = 0) {
+    const context = this.sessions.get(String(sessionKey));
+    if (!context) return;
+    context.activeUsers = (context.activeUsers || 0) + 1;
+    context.lastAccessedAt = Date.now();
+    context.persistedBytes = Math.max(0, Number(persistedBytes) || 0);
+  }
+
+  releaseCached(sessionKey, persistedBytes = 0) {
+    const context = this.sessions.get(String(sessionKey));
+    if (!context) return;
+    context.activeUsers = Math.max(0, (context.activeUsers || 0) - 1);
+    context.lastAccessedAt = Date.now();
+    context.persistedBytes = Math.max(0, Number(persistedBytes) || 0);
+  }
+
+  cacheUsage() {
+    return {
+      sessions: this.sessions.size,
+      persistedBytes: [...this.sessions.values()].reduce((total, context) => total + (context.persistedBytes || 0), 0)
+    };
+  }
+
+  cacheOverLimit() {
+    const usage = this.cacheUsage();
+    return usage.sessions > this.cachePolicy.maxSessions
+      || usage.persistedBytes > this.cachePolicy.maxPersistedBytes;
+  }
+
+  evictionCandidate(protectedKeys = new Set()) {
+    return [...this.sessions.entries()]
+      .filter(([key, context]) => !protectedKeys.has(key) && !(context.activeUsers > 0) && !context.session?.isStreaming)
+      .sort((left, right) => (left[1].lastAccessedAt || 0) - (right[1].lastAccessedAt || 0))[0];
+  }
+
+  async evictInactive({ protectedSessionKeys = [] } = {}) {
+    const protectedKeys = new Set(protectedSessionKeys.map(String));
+    const evicted = [];
+    let candidate = this.evictionCandidate(protectedKeys);
+    while (candidate) {
+      const [sessionKey, context] = candidate;
+      evicted.push({ sessionKey, persistedBytes: context.persistedBytes || 0 });
+      this.logger?.log("agent", `evicting inactive Pi session for chat ${sessionKey} from resident cache`);
+      await this.closeCached(sessionKey);
+      candidate = this.evictionCandidate(protectedKeys);
+    }
+    return evicted;
+  }
+
+  async enforceCachePolicy({ protectedSessionKeys = [] } = {}) {
+    const protectedKeys = new Set(protectedSessionKeys.map(String));
+    const evicted = [];
+    while (this.cacheOverLimit()) {
+      const candidate = this.evictionCandidate(protectedKeys);
+      if (!candidate) break;
+      const [sessionKey, context] = candidate;
+      evicted.push({ sessionKey, persistedBytes: context.persistedBytes || 0 });
+      this.logger?.log("agent", `evicting inactive Pi session for chat ${sessionKey} from resident cache`);
+      await this.closeCached(sessionKey);
+    }
+    return evicted;
   }
 
   closeCached(sessionKey) {
@@ -90,14 +167,19 @@ export class AgentSessionLifecycle {
     this.pendingSessionHandoffs.clear();
   }
 
-  resetSession(chatId, { handoff = "", parentSession = "" } = {}) {
+  resetSession(chatId, { handoff = "", parentSession = "", source = "" } = {}) {
     const sessionKey = String(chatId);
     this.closeCached(sessionKey);
     this.pendingNewSessions.add(sessionKey);
     const text = String(handoff || "").trim();
     const parent = String(parentSession || "").trim();
+    const handoffSource = String(source || "").trim();
     if (text || parent) {
-      this.pendingSessionHandoffs.set(sessionKey, { text, parentSession: parent });
+      this.pendingSessionHandoffs.set(sessionKey, {
+        text,
+        parentSession: parent,
+        ...(handoffSource ? { source: handoffSource } : {})
+      });
     } else {
       this.pendingSessionHandoffs.delete(sessionKey);
     }
@@ -106,6 +188,7 @@ export class AgentSessionLifecycle {
   createSessionManager(chatId, workspaceDir = arisaInstallDir, sessionRevision = 0) {
     const sessionKey = String(chatId);
     const sessionDir = getChatPiSessionsDir(sessionKey, sessionRevision);
+    const operationalNotes = formatSessionStartOperationalNotes(loadSessionStartOperationalNotes());
     if (this.pendingNewSessions.has(sessionKey)) {
       this.logger?.log("agent", `starting new persisted session for chat ${sessionKey}`);
       const handoff = this.pendingSessionHandoffs.get(sessionKey);
@@ -114,7 +197,6 @@ export class AgentSessionLifecycle {
         sessionDir,
         handoff?.parentSession ? { parentSession: handoff.parentSession } : undefined
       );
-      const operationalNotes = formatSessionStartOperationalNotes(loadSessionStartOperationalNotes());
       if (operationalNotes) {
         sessionManager.appendCustomMessageEntry(
           "arisa-operational-notes",
@@ -128,11 +210,23 @@ export class AgentSessionLifecycle {
           "arisa-session-handoff",
           handoff.text,
           false,
-          { source: "telegram-new" }
+          { source: handoff.source || "telegram-new" }
         );
       }
       return { sessionManager, isNewSession: true };
     }
+    const migration = migrateRecentSessionBeforeLoad({
+      sessionDir,
+      cwd: workspaceDir,
+      policy: this.sessionRotationPolicy,
+      operationalNotes
+    });
+    if (migration) {
+      this.logger?.log(
+        "agent",
+        `migrated oversized Pi session for chat ${sessionKey} before loading (${Math.ceil(migration.sourceBytes / 1024 / 1024)} MiB -> ${Math.ceil(migration.targetBytes / 1024 / 1024)} MiB)`
+      );
+    }
     this.logger?.log("agent", `recovering persisted session for chat ${sessionKey}`);
     return {
       sessionManager: SessionManager.continueRecent(workspaceDir, sessionDir),
@@ -147,7 +241,12 @@ export class AgentSessionLifecycle {
 
   async getDiagnostic() {
     const contexts = await Promise.all([...this.sessions.entries()].map(async ([chatId, context]) => {
-      const base = { chatId };
+      const base = {
+        chatId,
+        activeUsers: context.activeUsers || 0,
+        persistedBytes: context.persistedBytes || 0,
+        lastAccessedAt: context.lastAccessedAt || null
+      };
       try {
         const stats = context.session.getSessionStats();
         const retained = this.summarizeContext(context.session.messages);
@@ -166,6 +265,7 @@ export class AgentSessionLifecycle {
       harness: "pi",
       sessions: this.sessions.size,
       closingSessions: this.sessionClosePromises.size,
+      cache: { ...this.cachePolicy, ...this.cacheUsage() },
       contexts
     };
   }

package/src/core/agent/agent-turn-coordinator.js

@@ -0,0 +1,143 @@
+function normalizedPriority(value) {
+  if (value === "interactive") return 10;
+  if (value === "background") return 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.max(-100, Math.min(100, parsed)) : 0;
+}
+
+function positiveInteger(value, fallback, max) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.min(max, parsed) : fallback;
+}
+
+function queueExpiredError(label) {
+  const error = new Error(`${label || "Agent turn"} expired while waiting for exclusive execution.`);
+  error.code = "AGENT_TURN_QUEUE_EXPIRED";
+  error.retryable = true;
+  error.outcomeUncertain = false;
+  return error;
+}
+
+export class AgentTurnCoordinator {
+  constructor({ config = {}, logger = null, now = Date.now } = {}) {
+    this.logger = logger;
+    this.now = now;
+    this.queue = [];
+    this.active = null;
+    this.sequence = 0;
+    this.closed = false;
+    this.completed = 0;
+    this.expired = 0;
+    this.maxObservedQueue = 0;
+    this.totalWaitMs = 0;
+    this.setConfig(config);
+  }
+
+  setConfig(config = {}) {
+    this.config = {
+      enabled: config.enabled !== false,
+      backgroundQueueTtlMs: positiveInteger(config.backgroundQueueTtlMs, 10 * 60_000, 60 * 60_000),
+      interactiveQueueTtlMs: positiveInteger(config.interactiveQueueTtlMs, 0, 60 * 60_000),
+      maxQueued: Math.max(1, positiveInteger(config.maxQueued, 100, 1_000))
+    };
+  }
+
+  queueTtlMs(priority, override) {
+    if (override != null) return positiveInteger(override, 0, 60 * 60_000);
+    return priority === "interactive" ? this.config.interactiveQueueTtlMs : this.config.backgroundQueueTtlMs;
+  }
+
+  describeActive(entry) {
+    if (!entry) return null;
+    return { label: entry.label, priority: entry.priorityName, startedAt: entry.startedAt };
+  }
+
+  diagnostic() {
+    return {
+      enabled: this.config.enabled,
+      active: this.describeActive(this.active),
+      queued: this.queue.length,
+      maxObservedQueue: this.maxObservedQueue,
+      completed: this.completed,
+      expired: this.expired,
+      averageWaitMs: this.completed ? Math.round(this.totalWaitMs / this.completed) : 0
+    };
+  }
+
+  remove(entry) {
+    const index = this.queue.indexOf(entry);
+    if (index >= 0) this.queue.splice(index, 1);
+  }
+
+  next() {
+    if (this.active || this.closed || !this.queue.length) return;
+    this.queue.sort((left, right) => right.priority - left.priority || left.sequence - right.sequence);
+    const entry = this.queue.shift();
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.startedAt = new Date(this.now()).toISOString();
+    this.active = entry;
+    const waitMs = Math.max(0, this.now() - entry.queuedAt);
+    this.totalWaitMs += waitMs;
+    if (waitMs > 0) this.logger?.log("agent", `${entry.label} waited ${waitMs}ms for exclusive agent execution`);
+    let released = false;
+    entry.resolve(() => {
+      if (released) return;
+      released = true;
+      if (this.active === entry) this.active = null;
+      this.completed += 1;
+      queueMicrotask(() => this.next());
+    });
+  }
+
+  acquire({ priority: priorityName = "background", label = "Agent turn", queueTtlMs } = {}) {
+    if (!this.config.enabled) return Promise.resolve(() => {});
+    if (this.closed) return Promise.reject(Object.assign(new Error("Agent turn coordinator is closed."), { retryable: true }));
+    if (this.queue.length >= this.config.maxQueued) {
+      return Promise.reject(Object.assign(new Error("Agent turn queue is full."), { code: "AGENT_TURN_QUEUE_FULL", retryable: true }));
+    }
+    const priority = normalizedPriority(priorityName);
+    const ttlMs = this.queueTtlMs(priorityName, queueTtlMs);
+    return new Promise((resolve, reject) => {
+      const entry = {
+        label: String(label || "Agent turn").slice(0, 160),
+        priorityName: priorityName === "interactive" ? "interactive" : "background",
+        priority,
+        sequence: this.sequence += 1,
+        queuedAt: this.now(),
+        startedAt: null,
+        resolve,
+        reject,
+        timer: null
+      };
+      if (ttlMs > 0) {
+        entry.timer = setTimeout(() => {
+          if (this.active === entry) return;
+          this.remove(entry);
+          this.expired += 1;
+          reject(queueExpiredError(entry.label));
+        }, ttlMs);
+        entry.timer.unref?.();
+      }
+      this.queue.push(entry);
+      this.maxObservedQueue = Math.max(this.maxObservedQueue, this.queue.length);
+      this.next();
+    });
+  }
+
+  async run(options, work) {
+    const release = await this.acquire(options);
+    try {
+      return await work();
+    } finally {
+      release();
+    }
+  }
+
+  close() {
+    this.closed = true;
+    for (const entry of this.queue.splice(0)) {
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.reject(Object.assign(new Error("Agent turn coordinator closed before execution."), { retryable: true }));
+    }
+  }
+}

package/src/core/agent/core-tools.js

@@ -1,6 +1,6 @@
 import os from "node:os";
 import path from "node:path";
-import { arisaHomeDir } from "../../runtime/paths.js";
+import { arisaHomeDir } from "../../platform/paths.js";
 
 const defaultShellTimeoutMs = 60_000;
 

package/src/core/agent/pi-auth-login.js

@@ -1,5 +1,5 @@
 import { AuthStorage } from "@earendil-works/pi-coding-agent";
-import { piAuthFile } from "../../runtime/paths.js";
+import { piAuthFile } from "../../platform/paths.js";
 
 export function createPiOAuthLogin({ provider, onAuth, onDeviceCode, onPrompt, onProgress, onSelect } = {}) {
   const authStorage = AuthStorage.create(piAuthFile);