@phnx-labs/agents-cli 1.22.112 → 1.22.113

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.22.113
+
+- **Remote sessions have one execution-owned row (PHNX-3939).** Fleet session and feed streams reconcile launcher observations with the worker's state, retaining terminal/viewing metadata separately. Reconnects and stale history cannot replace a genuine worker row. Registry cleanup retains records whose PID namespace cannot be verified; nested agent runs keep launch lineage without claiming their parent's editor terminal.
+- **Codex forks retain their child identity.** Full and incremental scans keep the first native metadata record. Reindexing repairs cold files and removes a stale parent binding to child bytes even when the parent rollout is absent. Team descendants also keep their immediate parent lineage without inheriting its editor ownership.
+- **Nested daemon starts preserve shared session state.** Legacy migration and reboot recovery require the initial host namespace or kernel-verified live daemon ownership before touching singleton state. Foreign snapshots remain read-only, and invisible processes are never treated as dead. Automatic reuse of a private-container HOME across namespaces is unsupported, including after the prior namespace exits; writers fail safely with a diagnostic.
+
+- Repair session indexes whose schema version is current but whose identity columns are missing, preserving existing session metadata (PHNX-3940).
+
 ## 1.22.112
 
 - **Runs expand portable home paths on the executing device (PHNX-3940).** A remote resume terminal could open successfully while its child failed to start because `--cwd '$HOME'` was treated as a literal directory. The shared run path now expands `$HOME` and `~` locally, while preserving those anchors until remote dispatch reaches its target. This fixes direct runs and resumed conversations alike.

package/dist/commands/sessions.d.ts

@@ -31,6 +31,7 @@ interface SessionsOptions extends SessionFilterOptions {
     resolve?: string;
     /** Versioned internal peer protocol; old/unsafe peers must reject it. */
     resolveSafeV1?: string;
+    resolveLaunchId?: string;
     limit?: string;
     sort?: string;
     json?: boolean;

package/dist/commands/sessions.js

@@ -2367,6 +2367,17 @@ limitSource) {
         process.stdout.write(JSON.stringify(getSessionRoots(), null, 2) + '\n');
         return;
     }
+    if (options.resolveLaunchId !== undefined) {
+        if (!options.json)
+            throw new Error('--resolve-launch-id requires --json.');
+        const launchId = options.resolveLaunchId.trim();
+        if (!launchId)
+            throw new Error('--resolve-launch-id requires a non-empty launch id.');
+        const { loadHookSessionIndex } = await import('../lib/session/hook-sessions.js');
+        const record = loadHookSessionIndex().byLaunchId.get(launchId);
+        process.stdout.write(JSON.stringify({ launchId, sessionId: record?.session_id ?? null }) + '\n');
+        return;
+    }
     // --resolve is the metadata-only contract for downstream context workflows.
     // It reads indexed SessionMeta rows and never calls renderSession, buildPreview,
     // parseSession, or any other transcript renderer/parser.
@@ -5160,6 +5171,7 @@ export function registerSessionsCommands(program) {
         .option('--query <clause>', 'Search text; repeat with --include tools to require distinct matching calls', collectQueryClause, [])
         .option('--resolve <selector>', 'Resolve one full ID, unique prefix, or keyword query to safe session metadata (requires --json; searches the fleet unless --local)')
         .addOption(new Option('--resolve-safe-v1 <selector>').hideHelp())
+        .addOption(new Option('--resolve-launch-id <id>').hideHelp())
         .description('Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active`.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .addOption(new Option('--session-version <version>', 'Internal spelling for the public sessions --version filter')

package/dist/lib/daemon/daemon.d.ts

@@ -1,11 +1,3 @@
-/**
- * Daemon lifecycle management for the routines scheduler.
- *
- * The daemon is a long-running process that holds a JobScheduler and
- * triggers jobs on their cron schedules. It can be managed via launchd
- * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
- * log output, reload (SIGHUP), and graceful shutdown are handled here.
- */
 import { isolatedHomeSuffix } from '../service-manifest.js';
 import { getAgentsBinPath } from '../cli-entry.js';
 import type { ServiceHealth } from './service.js';

package/dist/lib/daemon/daemon.js

@@ -1,3 +1,4 @@
+import { daemonProcessViewAllowed, recordDaemonProcessView } from '../session/process-view.js';
 /**
  * Daemon lifecycle management for the routines scheduler.
  *
@@ -22,7 +23,6 @@ import { detectOverdueJobs, notifyOverdue } from '../overdue.js';
 import { runCatchup } from '../catchup.js';
 import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from '../routine-notify.js';
 import { notifyOwnerRoutineFinish, notifyOwnerRoutineStartFailed } from '../routine-notify-owner.js';
-import { BrowserService } from '../browser/service.js';
 import { getSocketPath as getBrowserIpcSocketPath } from '../browser/ipc.js';
 import { redactSecrets } from '../redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from '../cli-entry.js';
@@ -30,27 +30,6 @@ import { localBinDir } from '../platform/posixpath.js';
 import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled } from '../device-config.js';
 import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, readSubsystemHealth, SUBSYSTEM_DAEMON_START } from '../daemon-health.js';
 import { ServiceSupervisor } from './supervisor.js';
-import { SessionIndexService } from './session-index-service.js';
-import { SessionSummarizerService } from './session-summarizer-service.js';
-import { SessionTitleService } from './session-title-service.js';
-import { MonitorEngineService } from './monitor-engine-service.js';
-import { AccountUsageService, AccountAuthService } from './account-state-daemon-service.js';
-import { CatchupService } from './catchup-service.js';
-import { BrowserIPCService } from './browser-ipc-service.js';
-import { WatchdogService } from './watchdog-service.js';
-import { DeviceProbeService } from './device-probe-service.js';
-import { SelfHealService } from './self-heal-service.js';
-import { SelfUpdateService } from './self-update-service.js';
-import { HarnessUpdateService } from './harness-update-service.js';
-import { AuthSyncService } from './auth-sync-service.js';
-import { UsageSyncService } from './usage-sync-service.js';
-import { StateDirCheckService } from './state-dir-check-service.js';
-import { SessionStateService } from './session-state-service.js';
-import { AttentionNotifyService } from './attention-notify-service.js';
-import { WebhookReceiverService } from './webhook-receiver-service.js';
-import { HeartbeatService } from './heartbeat-service.js';
-import { TmuxReapService } from './tmux-reap-service.js';
-import { BrowserTaskReapService } from './browser-task-reap-service.js';
 import { emit, emitAsync, emitRoutineEnd } from '../feed/events.js';
 import { readDaemonServicesConfig, drainDaemonServiceRestartQueue } from '../daemon-services.js';
 import { sleepSync } from '../fs-atomic.js';
@@ -478,6 +457,12 @@ export function isDaemonRunning() {
  * liveness check and the write.
  */
 export function claimDaemonInstance() {
+    // A nested caller cannot interpret legacy numeric lock/PID files. Authenticate
+    // before acquiring the lock (whose stale-PID cleanup itself mutates state).
+    if (!daemonProcessViewAllowed()) {
+        console.error('Daemon startup requires the owning process namespace. Automatic reuse of a private-container HOME across namespaces is unsupported; run in its owning namespace or use a fresh HOME.');
+        return false;
+    }
     // A stop owns this same lock through teardown. Waiting here is load-bearing:
     // returning false while stopDaemon() holds it lets this replacement exit 0,
     // then the stop completes with no singleton left alive. The bounded lifecycle
@@ -488,6 +473,10 @@ export function claimDaemonInstance() {
     if (!release)
         return false;
     try {
+        // Recheck under lifecycle serialization; invocation is not provenance.
+        if (!daemonProcessViewAllowed())
+            return false;
+        recordDaemonProcessView();
         // Do not overwrite a live-but-uninspectable owner. This is the non-
         // destructive side of the same fail-closed rule stopDaemon applies.
         if (unverifiedLiveDaemonPid() !== null)
@@ -887,6 +876,32 @@ export async function runDaemon() {
     // HOME override must refuse to run against the operator's real state rather than
     // schedule against the real host. No-op in production (the marker is never set).
     assertTestDaemonHome();
+    // Lifecycle readers and launchers do not run services. Load their code only
+    // in the daemon process, before it claims or publishes lifecycle state.
+    const [{ BrowserService }, { SessionIndexService }, { SessionSummarizerService }, { SessionTitleService }, { MonitorEngineService }, { AccountUsageService, AccountAuthService }, { CatchupService }, { BrowserIPCService }, { WatchdogService }, { DeviceProbeService }, { SelfHealService }, { SelfUpdateService }, { HarnessUpdateService }, { AuthSyncService }, { UsageSyncService }, { StateDirCheckService }, { SessionStateService }, { AttentionNotifyService }, { WebhookReceiverService }, { HeartbeatService }, { TmuxReapService }, { BrowserTaskReapService },] = await Promise.all([
+        import('../browser/service.js'),
+        import('./session-index-service.js'),
+        import('./session-summarizer-service.js'),
+        import('./session-title-service.js'),
+        import('./monitor-engine-service.js'),
+        import('./account-state-daemon-service.js'),
+        import('./catchup-service.js'),
+        import('./browser-ipc-service.js'),
+        import('./watchdog-service.js'),
+        import('./device-probe-service.js'),
+        import('./self-heal-service.js'),
+        import('./self-update-service.js'),
+        import('./harness-update-service.js'),
+        import('./auth-sync-service.js'),
+        import('./usage-sync-service.js'),
+        import('./state-dir-check-service.js'),
+        import('./session-state-service.js'),
+        import('./attention-notify-service.js'),
+        import('./webhook-receiver-service.js'),
+        import('./heartbeat-service.js'),
+        import('./tmux-reap-service.js'),
+        import('./browser-task-reap-service.js'),
+    ]);
     // Install the shared-daemon reload signal boundary BEFORE publishing our PID
     // in claimDaemonInstance(). Browser/routines clients use that PID to decide a
     // daemon exists and may request a service reload immediately. POSIX otherwise
@@ -1739,6 +1754,10 @@ function assertDaemonLaunchHomeAllowed() {
 }
 /** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon(agentsBin) {
+    // The public launcher must obey the same namespace boundary as its child:
+    // even probing/repairing legacy PID state or pruning a lock can mutate it.
+    if (!daemonProcessViewAllowed())
+        throw new Error('Daemon startup requires the owning process namespace. Automatic reuse of a private-container HOME across namespaces is unsupported; run in its owning namespace or use a fresh HOME.');
     if (isDaemonRunning()) {
         const pid = readDaemonPid();
         return { pid, method: 'already-running' };

package/dist/lib/daemon/testdata/process-view-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/daemon/testdata/process-view-daemon.js

@@ -0,0 +1,14 @@
+// Runs the production daemon entrypoint against an isolated HOME. No installed
+// CLI, service manager, scheduler, or production socket participates.
+import { runDaemon, startDaemon } from '../daemon.js';
+if (process.argv[2] === '__start-daemon') {
+    try {
+        startDaemon();
+    }
+    catch (error) {
+        console.log(error.message);
+        process.exitCode = 2;
+    }
+}
+else
+    await runDaemon();

package/dist/lib/daemon/testdata/process-view-start.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/daemon/testdata/process-view-start.js

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { serviceManagerRegistrationAllowed } from '../../service-manifest.js';
+import { startDaemon, stopDaemon } from '../daemon.js';
+import { getDaemonDir, getTerminalsDir, getCacheDir } from '../../state.js';
+// Tripwire precedes ALL lifecycle calls. Some older Bun versions return HOME
+// from os.userInfo(), which would incorrectly allow the real service manager.
+assert.equal(serviceManagerRegistrationAllowed().allowed, false, 'isolated fixture must never access the production service manager');
+const cold = process.argv[3] === 'cold';
+const child = cold ? spawn('bun', [process.argv[4], '__daemon-run'], { stdio: 'ignore', env: process.env }) : undefined;
+const started = child ? { pid: child.pid, method: 'detached' } : startDaemon(process.argv[2]);
+assert.equal(started.method, 'detached');
+assert.ok(started.pid);
+fs.writeFileSync(path.join(process.env.HOME, 'test-child.pid'), String(started.pid));
+try {
+    if (!cold)
+        assert.ok(fs.existsSync(path.join(getDaemonDir(), 'health.json')), 'ordinary launcher publishes health before daemon starts');
+    const socket = path.join(getCacheDir(), 'helpers', 'browser', 'browser.sock');
+    let ready = false;
+    for (let i = 0; i < 80 && !ready; i++) {
+        ready = await new Promise(resolve => {
+            const client = net.createConnection(socket);
+            const done = (value) => { client.destroy(); resolve(value); };
+            client.setTimeout(100, () => done(false));
+            client.once('connect', () => done(true));
+            client.once('error', () => done(false));
+        });
+        if (!ready)
+            await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.ok(ready, 'ordinary fresh-home daemon must serve its actual browser socket');
+    assert.equal(fs.readFileSync(path.join(getDaemonDir(), 'daemon.pid'), 'utf8').trim(), String(started.pid));
+    const owner = JSON.parse(fs.readFileSync(path.join(getTerminalsDir(), 'process-view.json'), 'utf8'));
+    assert.equal(owner.pidNamespace, fs.readlinkSync('/proc/self/ns/pid'));
+    assert.equal(owner.bootId, fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim());
+    console.log(`${cold ? 'cold runDaemon' : 'ordinary startDaemon: health published'}; canonical socket ready; namespace owner verified`);
+}
+finally {
+    stopDaemon();
+}

package/dist/lib/event-provenance.d.ts

@@ -10,6 +10,8 @@ export interface EventProvenance {
     agent?: string;
     launchId?: string;
     parentSessionId?: string;
+    parentLaunchId?: string;
+    originTerminalId?: string;
 }
 /**
  * Stamp the shared identity floor used by both operational and activity events.

package/dist/lib/event-provenance.js

@@ -40,6 +40,10 @@ export function stampProvenance(env = process.env) {
         provenance.launchId = env.AGENT_LAUNCH_ID;
     if (env.AGENTS_PARENT_SESSION_ID)
         provenance.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
+    if (env.AGENTS_PARENT_LAUNCH_ID)
+        provenance.parentLaunchId = env.AGENTS_PARENT_LAUNCH_ID;
+    if (env.AGENTS_ORIGIN_TERMINAL_ID)
+        provenance.originTerminalId = env.AGENTS_ORIGIN_TERMINAL_ID;
     return provenance;
 }
 export function resetEventProvenanceForTest() {

package/dist/lib/exec.js

@@ -1,3 +1,4 @@
+import { captureLaunchBinding, recordCompletedLaunch } from './session/hook-sessions.js';
 /**
  * Agent execution -- command building, process spawning, and rate-limit fallback.
  *
@@ -17,6 +18,7 @@ import { isTierToken, resolveTier } from './model-tiers.js';
 import { emit, createTimer, redactPrompt, redactArgs } from './feed/events.js';
 import { sanitizeProcessEnv } from './secrets-client.js';
 import { resolveActor, actorEnv } from './actor.js';
+import { launchIdentityEnv, LAUNCH_IDENTITY_KEYS } from './launch-identity.js';
 import { expandLocalHome } from './project-root.js';
 import { getShimsDir, getHistoryDir, getUserAgentsDir, getRuntimeStateDir } from './state.js';
 import { readCodexConfiguredModel } from './installations/shims.js';
@@ -378,6 +380,14 @@ export function buildExecEnv(options) {
     else {
         stripForeignConfigDir(result);
     }
+    // A new harness must not inherit its spawner's own session/mailbox or editor
+    // ownership. Keep those relationships as lineage, including across SSH.
+    delete result.AGENT_SESSION_ID;
+    delete result.AGENTS_SESSION_ID;
+    delete result.AGENTS_MAILBOX_DIR;
+    delete result.AGENT_TERMINAL_ID;
+    const launchIdentity = launchIdentityEnv();
+    Object.assign(result, launchIdentity);
     // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
     // knows which box to drain and inject mid-run. Keyed by the session id — the
     // same id the writer resolves via mailboxIdForActiveSession(). A loop run
@@ -394,9 +404,9 @@ export function buildExecEnv(options) {
     // (events.ts::resolveProvenance) reads AGENTS_PARENT_SESSION_ID and stamps it on
     // every event the child emits. `options.sessionId` is the CHILD's id, so read the
     // spawner from the live env; guard a same-session resume from naming itself parent.
-    // Local-spawn scope here; forwarding it across the `--device` SSH hop is Phase 4.
+    // An SSH continuation has no runtime marker; keep its forwarded parent edge.
     delete result.AGENTS_PARENT_SESSION_ID;
-    const spawnerSessionId = process.env.AGENTS_SESSION_ID || process.env.AGENT_SESSION_ID;
+    const spawnerSessionId = launchIdentity.AGENTS_PARENT_SESSION_ID;
     if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
     }
@@ -1210,7 +1220,7 @@ async function execShimPassthroughLeased(agent, rawArgs, cwd, pinnedVersion) {
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
                 launchId,
-                terminalId: process.env.AGENT_TERMINAL_ID,
+                terminalId: launchIdentityEnv().AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
             // Durable sessionId -> actor record (RUSH-2019) so the scanner can attribute
@@ -1347,6 +1357,7 @@ export function isHarnessKnownSessionId(agent, sessionId, resume) {
  */
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
+    const absentIdentity = LAUNCH_IDENTITY_KEYS.filter(key => env[key] === undefined);
     // envFile: source the values instead of inlining them, so no VALUE ever lands
     // in the pane's argv. `exec env K=V …` put every resolved secret into the
     // process table, readable by any process of this user — on one fleet box six
@@ -1361,13 +1372,13 @@ export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
         // strands the plaintext env (incl. the secrets-store master passphrase) on
         // disk on any source failure, worse than the argv leak this replaces
         // (RUSH-2100). Capture the source rc, unlink, then honor it.
-        return `set -a; . ${f}; __agents_rc=$?; set +a; rm -f ${f}; [ "$__agents_rc" -eq 0 ] || exit 1; exec ${agentCmd}`;
+        return `${absentIdentity.length ? `unset ${absentIdentity.join(' ')}; ` : ''}set -a; . ${f}; __agents_rc=$?; set +a; rm -f ${f}; [ "$__agents_rc" -eq 0 ] || exit 1; exec ${agentCmd}`;
     }
     const envPrefix = Object.entries(env)
         .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
         .map(([k, v]) => `${k}=${opts.redactEnvValues ? '<redacted>' : shellQuote(String(v))}`)
         .join(' ');
-    return `exec env ${envPrefix} ${agentCmd}`;
+    return `exec env ${absentIdentity.map(key => `-u ${key}`).join(' ')} ${envPrefix} ${agentCmd}`;
 }
 /**
  * Serialize the pane env to a shell-sourceable file, created 0600 and exclusively
@@ -1493,9 +1504,14 @@ async function runInTmux(options, executable, args) {
      * "the session went away underneath us", so an attach that skips this cannot
      * do better than assume success — which is exactly the defect EXEC-23b fixes.
      */
+    let paneLaunchBinding;
+    const bindCompletedPane = () => {
+        recordCompletedLaunch(paneLaunchBinding);
+    };
     const resolveAfterAttach = async (pane) => {
         const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
         if (after.dead) {
+            bindCompletedPane();
             // Positive proof of a genuinely completed pane (paneExitStatus confirmed
             // dead) — capture its scrollback as refusal evidence for the caller
             // (classifyClaudeRunRefusal etc.) BEFORE tearing the session down.
@@ -1633,10 +1649,11 @@ async function runInTmux(options, executable, args) {
             // pid) reconciles by launchId. This pane's pid usually IS the agent pid,
             // but the launchId join is robust even when it isn't.
             launchId: options.env?.AGENT_LAUNCH_ID,
-            terminalId: process.env.AGENT_TERMINAL_ID,
+            terminalId: launchIdentityEnv().AGENT_TERMINAL_ID,
             tmuxPane: pane,
             startedAtMs: Date.now(),
         });
+        paneLaunchBinding = captureLaunchBinding(panePid, options.env?.AGENT_LAUNCH_ID ?? '');
         if (options.sessionId) {
             writeSessionActorRecord({
                 sessionId: options.sessionId,
@@ -1653,6 +1670,7 @@ async function runInTmux(options, executable, args) {
     // already-dead pane — surface its output + status directly and tear down.
     const before = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (before.dead) {
+        bindCompletedPane();
         // Positive proof of a genuinely completed pane — capture scrollback as
         // refusal evidence before tearing the session down (see the matching
         // comment in resolveAfterAttach).
@@ -2071,10 +2089,11 @@ async function spawnAgentLeased(options) {
             actor: resolveActor().id,
             initiatedBy: resolveActor().kind,
             launchId,
-            terminalId: process.env.AGENT_TERMINAL_ID,
+            terminalId: launchIdentityEnv().AGENT_TERMINAL_ID,
             tmuxPane: process.env.TMUX_PANE,
             startedAtMs: Date.now(),
         });
+        const launchBinding = captureLaunchBinding(child.pid, launchId);
         if (options.sessionId) {
             writeSessionActorRecord({
                 sessionId: options.sessionId,
@@ -2146,6 +2165,7 @@ async function spawnAgentLeased(options) {
             reject(err);
         });
         child.on('close', (code) => {
+            recordCompletedLaunch(launchBinding);
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
             // Clear the budget-kill SIGKILL escalation timer (mirror the --timeout

package/dist/lib/feed/activity-stream.js

@@ -56,6 +56,15 @@ export class ActivityStream {
         this.maxBytesPerRead = options.maxBytesPerRead ?? ACTIVITY_TAIL_BYTES;
         this.sweepMs = options.sweepMs ?? ACTIVITY_SWEEP_MS;
         this.watchRequested = options.watch ?? true;
+        // A log directory that does not exist yet (nothing has logged activity
+        // since boot) means fs.watch below throws ENOENT and never retries except
+        // on the bounded sweep cadence — the very first session's activity can
+        // then sit unwatched for up to `sweepMs` before it is even noticed.
+        // Creating it up front lets the watcher arm immediately.
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+        }
+        catch { /* best-effort: sweep() covers a dir that still isn't there */ }
         this.sweep(Date.now());
         this.armWatcher();
     }

package/dist/lib/feed/activity.d.ts

@@ -136,6 +136,14 @@ export declare function appendActivityEvent(event: Omit<ActivityEvent, 'v' | 'ti
 export declare function parseActivityLine(line: string): ActivityEvent | undefined;
 /** Per-session byte budget for a bounded tail read of an activity log. */
 export declare const ACTIVITY_TAIL_BYTES: number;
+/** Read-only process-local diagnostics; no event content or file paths. */
+export declare function getActivityCacheStats(): {
+    entries: number;
+    parsedTails: number;
+    bytes: number;
+    maxBytes: number;
+    tailReads: number;
+};
 /** Read all events for one session (bounded tail). */
 export declare function readSessionActivity(sessionId: string, root?: string, maxBytes?: number): ActivityEvent[];
 /** List session ids that have an activity log. */

package/dist/lib/feed/activity.js

@@ -198,14 +198,67 @@ function readTail(file, maxBytes) {
 // sessions or directories a long-lived consumer visits. Never expose cached
 // objects: callers enrich and mutate returned events (including nested values).
 const ACTIVITY_CACHE_BYTES = 32 * 1024 * 1024;
-const ACTIVITY_CACHE_FILES = 1024;
 const activityTails = new Map();
+// A separate LRU of payload references lets pressure release parsed events
+// without repeatedly walking thousands of summaries that cannot shrink.
+const activityTailPayloads = new Map();
 let activityTailBytes = 0;
+let activityTailReads = 0;
+/** Read-only process-local diagnostics; no event content or file paths. */
+export function getActivityCacheStats() {
+    return {
+        entries: activityTails.size,
+        parsedTails: activityTailPayloads.size,
+        bytes: activityTailBytes,
+        maxBytes: ACTIVITY_CACHE_BYTES,
+        tailReads: activityTailReads,
+    };
+}
 function forgetActivityTail(key) {
     const old = activityTails.get(key);
     if (old)
         activityTailBytes -= old.weight;
     activityTails.delete(key);
+    activityTailPayloads.delete(key);
+}
+function activitySummaryWeight(key, stamp) {
+    return (key.length + stamp.length) * 2 + 256;
+}
+function retainActivityTail(key, result, sinceMs) {
+    const summaryWeight = activitySummaryWeight(key, result.stamp);
+    // Even metadata is byte-bounded. A tail whose summary cannot fit still
+    // returns normally, but must not evict the cache or be retained over budget.
+    if (summaryWeight > ACTIVITY_CACHE_BYTES)
+        return;
+    const retained = { ...result };
+    if (result.newestMs < sinceMs || result.weight > ACTIVITY_CACHE_BYTES / 2) {
+        retained.events = undefined;
+        retained.weight = summaryWeight;
+    }
+    // Prefer compact history over payloads, retaining all summaries that fit
+    // instead of imposing a file-count cap that thrashes on each directory scan.
+    for (const [oldKey, old] of activityTailPayloads) {
+        if (activityTailBytes + retained.weight <= ACTIVITY_CACHE_BYTES)
+            break;
+        const weight = activitySummaryWeight(oldKey, old.stamp);
+        activityTailBytes -= old.weight - weight;
+        old.events = undefined;
+        old.weight = weight;
+        activityTailPayloads.delete(oldKey);
+    }
+    // If all existing entries are summaries, sacrifice the incoming payload
+    // before evicting history. The current caller still receives result.events.
+    if (activityTailBytes + retained.weight > ACTIVITY_CACHE_BYTES) {
+        retained.events = undefined;
+        retained.weight = summaryWeight;
+    }
+    while (activityTailBytes + retained.weight > ACTIVITY_CACHE_BYTES) {
+        forgetActivityTail(activityTails.keys().next().value);
+    }
+    activityTails.set(key, retained);
+    if (retained.events)
+        activityTailPayloads.set(key, retained);
+    activityTailBytes += retained.weight;
 }
 function activityStamp(file) {
     // ctime catches same-size rewrites even when a producer restores mtime;
@@ -228,9 +281,14 @@ function readActivityTail(file, maxBytes, sinceMs = -Infinity) {
     if (cached?.stamp === stamp && (cached.events || cached.newestMs < sinceMs)) {
         activityTails.delete(key);
         activityTails.set(key, cached);
+        if (cached.events) {
+            activityTailPayloads.delete(key);
+            activityTailPayloads.set(key, cached);
+        }
         return cached;
     }
     forgetActivityTail(key);
+    activityTailReads++;
     const text = readTail(file, maxBytes);
     // Transient I/O failure is not an empty file snapshot; retry next read.
     if (text === undefined)
@@ -256,27 +314,12 @@ function readActivityTail(file, maxBytes, sinceMs = -Infinity) {
     }
     // Bound retained source-derived strings, objects, and entry overhead. Large
     // one-off tails still read normally, but cannot displace the entire cache.
-    const weight = text.length * 2 + events.length * 1024 + key.length * 2 + 256;
+    const weight = text.length * 2 + events.length * 1024 + activitySummaryWeight(key, stamp);
     const result = { stamp, events, newestMs, weight };
     try {
         // A writer racing the read must not pin a mixed snapshot as unchanged.
         if (activityStamp(file) === stamp) {
-            if (activityTails.size >= ACTIVITY_CACHE_FILES)
-                forgetActivityTail(activityTails.keys().next().value);
-            const summaryWeight = key.length * 2 + 256;
-            const retained = weight <= ACTIVITY_CACHE_BYTES / 2 ? { ...result } : { ...result, events: undefined, weight: summaryWeight };
-            // Retain timestamp summaries even when parsed tails exceed the budget:
-            // otherwise a large historical corpus thrashes on every cursor poll.
-            for (const [oldKey, old] of activityTails) {
-                if (activityTailBytes + retained.weight <= ACTIVITY_CACHE_BYTES)
-                    break;
-                const summary = oldKey.length * 2 + 256;
-                activityTailBytes -= old.weight - summary;
-                old.events = undefined;
-                old.weight = summary;
-            }
-            activityTails.set(key, retained);
-            activityTailBytes += retained.weight;
+            retainActivityTail(key, result, sinceMs);
         }
     }
     catch { /* Deleted during the read: return this snapshot without caching. */ }

package/dist/lib/feed/watch.d.ts

@@ -48,6 +48,15 @@ export declare class FeedWatchState {
     constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
     emit(event: FeedWatchPayload): FeedWatchEnvelope;
 }
+/** Reuse session ownership reconciliation for the combined operator stream. */
+export declare class FeedSessionProjection {
+    private readonly state;
+    private readonly sessions;
+    private readonly observations;
+    private projectedAttention;
+    constructor(state?: FeedWatchState);
+    apply(event: FeedWatchEnvelope): FeedWatchEnvelope[];
+}
 export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState, gh?: GhExec): Promise<FeedWatchEnvelope[]>;
 export interface WatchLocalFeedOptions {
     scope: string;