@phnx-labs/agents-cli 1.22.82 → 1.22.84

package/dist/lib/accounts/connect.js

@@ -1,12 +1,20 @@
 import * as crypto from 'node:crypto';
 import { nativeAccountCapability, nativeAccountNamingRefusal } from '../account-capabilities.js';
 import { listNativeAccounts } from '../account-registry.js';
+import { providerAuthenticatesHarness } from '../account-provider-registry.js';
+import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../device-config.js';
+import { machineId } from '../machine-id.js';
 import { readMeta } from '../state.js';
 import { acquireAuthOperationLock } from './auth-operation-lock.js';
 /**
  * `agents accounts connect <harness> [name]` — the stable-account front door
  * (PHNX-3940).
  *
+ * Headed devices only. A worker (or unmarked box) is refused before any slot,
+ * install, or browser login — workers never run an interactive OAuth flow
+ * (credential-management.md invariant 7). Add the account on a personal/desktop
+ * box; workers are provisioned from the durable credential.
+ *
  * An account is stable INDEPENDENT of releases: connecting a NEW account mints a
  * fresh opaque installation label, installs the current release into that
  * label's isolated home (even when the same release is already installed under
@@ -75,6 +83,65 @@ export function assertConnectSupported(agent) {
     if (reason)
         throw new Error(reason);
 }
+/**
+ * Native API-key provider for a harness that `connect` can drive AND that
+ * workers provision from a portable credential (credential-management.md
+ * invariant 7). The id is the registry adapter that authenticates this harness
+ * with `api-key` — not a parallel invention. Claude is a setup-token, not an
+ * API key, and is handled separately. Only LOGIN_INVOCATIONS harnesses belong
+ * here; a mapping for a harness connect cannot drive is dead code.
+ */
+const NATIVE_API_KEY_PROVIDER = {
+    codex: 'openai',
+};
+function nativeApiKeyProvider(agent) {
+    const id = NATIVE_API_KEY_PROVIDER[agent];
+    if (!id)
+        return null;
+    if (!providerAuthenticatesHarness(id, 'api-key', agent)) {
+        throw new Error(`Internal: provider '${id}' does not authenticate ${agent} with an api-key.`);
+    }
+    return id;
+}
+function workerCredentialHint(agent, name, device) {
+    if (agent === 'claude')
+        return 'the setup-token minted by agents accounts mint claude';
+    const provider = nativeApiKeyProvider(agent);
+    if (provider) {
+        const account = name ?? '<name>';
+        return `a provider API key — agents accounts add ${account} --provider ${provider} --auth api-key then agents accounts sync ${account} ${device}`;
+    }
+    // LOGIN_INVOCATIONS today is {claude, codex}; this arm is the loud failure
+    // if a future harness is added there without a portable-credential mapping.
+    // Names no command — a guessed `fleet login <harness>` is not a real invocation.
+    return `no portable credential for ${agent}`;
+}
+/**
+ * Named reason connect refuses on a non-headed device, or null when this box
+ * may run an interactive login. Workers never mint a native OAuth login
+ * (credential-management.md invariant 7 + Provisioning model).
+ */
+export function connectWorkerRefusal(agent, name) {
+    const role = selfConfiguredDeviceRole();
+    if (isHeadedDeviceRole(role))
+        return null;
+    const device = machineId();
+    const roleLabel = role ?? 'unmarked';
+    const selector = name ? `${agent}#${name}` : agent;
+    const connectCmd = name
+        ? `agents accounts connect ${agent} ${name}`
+        : `agents accounts connect ${agent} <name>`;
+    return `${selector}: this device is a worker (role ${roleLabel}) and never runs an interactive login. `
+        + `Add the account on your personal device with \`${connectCmd}\`; `
+        + `workers are provisioned from the durable credential automatically `
+        + `(${agent}: ${workerCredentialHint(agent, name, device)}). `
+        + `To mark this box as your interactive seat: agents devices role ${device} personal.`;
+}
+function assertConnectAllowedOnThisDevice(agent, name) {
+    const reason = connectWorkerRefusal(agent, name);
+    if (reason)
+        throw new Error(reason);
+}
 export function loginInvocation(agent) {
     const invocation = LOGIN_INVOCATIONS[agent];
     if (!invocation)
@@ -194,6 +261,9 @@ export function findConnectAccount(agent, name, meta) {
  */
 export async function runConnect(agent, name, opts, runners) {
     assertConnectSupported(agent);
+    // Owner rule (invariant 7): a worker NEVER runs an interactive login. Refuse
+    // before the lock, slot, install, or browser — no side effects on a worker.
+    assertConnectAllowedOnThisDevice(agent, name);
     // Acquire the per-harness auth-operation mutex BEFORE any meta read, slot
     // allocation, or name validation — two parallel connects for the same harness
     // would otherwise both see "name available" and "slot free", then race to

package/dist/lib/claude-statusline.d.ts

@@ -1,4 +1,5 @@
 import { type ClaudeHomeIdentity } from './agent-spec/agents.js';
+import { type NativeAccount } from './account-registry.js';
 export declare const CLAUDE_STATUSLINE_COMMAND = "agents __claude-statusline";
 /**
  * True when `command` re-invokes THIS status-line producer (our private
@@ -45,12 +46,19 @@ export declare function claudeHomeFromEnv(env: NodeJS.ProcessEnv): string;
  */
 export declare function readClaudeIdentity(claudeHome: string): ClaudeHomeIdentity | null;
 /**
- * Format the signed-in account as a statusline part ('' when never signed in),
- * with the label every other account-aware surface (`agents view`, `agents
- * accounts`) uses — the email, plus the org name for a multi-seat Team/Enterprise
- * seat.
+ * The registered native account for the running Claude's identity (`agents
+ * accounts` — `work`, `dev`, …), or null when that login is unnamed.
  */
-export declare function formatAccountPart(identity: ClaudeHomeIdentity | null): string;
+export declare function resolveNativeAccount(identity: ClaudeHomeIdentity | null): NativeAccount | null;
+/**
+ * Format the signed-in account as a statusline part ('' when never signed in).
+ * A named login renders its registered NAME — the short handle the owner chose
+ * (`work`, `dev`), which is what tells eight same-harness logins apart at a
+ * glance. An unnamed login renders the label every other account-aware surface
+ * (`agents view`, `agents accounts`) uses: the email, plus the org name for a
+ * multi-seat Team/Enterprise seat.
+ */
+export declare function formatAccountPart(identity: ClaudeHomeIdentity | null, account: NativeAccount | null): string;
 export declare function renderDelegate(payload: string, versionHome: string): string;
 /**
  * Format a reminder as a dimmed statusline part (empty string when none). The

package/dist/lib/claude-statusline.js

@@ -3,9 +3,11 @@ import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { accountDisplayLabel, readClaudeHomeConfig, } from './agent-spec/agents.js';
+import { findNativeAccountByIdentity } from './account-registry.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { mergeClaudeUsageCacheWindows } from './accounting/usage.js';
 import { loadReminders, pickReminderForSession } from './reminders.js';
+import { readMeta } from './state.js';
 export const CLAUDE_STATUSLINE_COMMAND = 'agents __claude-statusline';
 const DELEGATE_FILE = path.join('.agents', 'claude-statusline-delegate');
 // The private subcommand this feature runs. It is only ever invoked internally,
@@ -97,14 +99,25 @@ export function readClaudeIdentity(claudeHome) {
     return readClaudeHomeConfig(claudeHome)?.identity ?? null;
 }
 /**
- * Format the signed-in account as a statusline part ('' when never signed in),
- * with the label every other account-aware surface (`agents view`, `agents
- * accounts`) uses — the email, plus the org name for a multi-seat Team/Enterprise
- * seat.
+ * The registered native account for the running Claude's identity (`agents
+ * accounts` — `work`, `dev`, …), or null when that login is unnamed.
  */
-export function formatAccountPart(identity) {
+export function resolveNativeAccount(identity) {
+    return identity ? findNativeAccountByIdentity(readMeta(), 'claude', identity) : null;
+}
+/**
+ * Format the signed-in account as a statusline part ('' when never signed in).
+ * A named login renders its registered NAME — the short handle the owner chose
+ * (`work`, `dev`), which is what tells eight same-harness logins apart at a
+ * glance. An unnamed login renders the label every other account-aware surface
+ * (`agents view`, `agents accounts`) uses: the email, plus the org name for a
+ * multi-seat Team/Enterprise seat.
+ */
+export function formatAccountPart(identity, account) {
     if (!identity)
         return '';
+    if (account)
+        return account.name;
     return accountDisplayLabel({ ...identity, signedIn: true });
 }
 function delegatePath(versionHome) {
@@ -194,7 +207,7 @@ export async function runClaudeStatusLine() {
     const identity = readClaudeIdentity(claudeHomeFromEnv(process.env));
     if (versionHome)
         ingestClaudeStatusLineUsage(payload, identity);
-    process.stdout.write(renderClaudeStatusLine(payload, undefined, versionHome ? renderDelegate(raw, versionHome) : '', resolveReminderPart(payload.session_id), formatAccountPart(identity)));
+    process.stdout.write(renderClaudeStatusLine(payload, undefined, versionHome ? renderDelegate(raw, versionHome) : '', resolveReminderPart(payload.session_id), formatAccountPart(identity, resolveNativeAccount(identity))));
     return 0;
 }
 export function installClaudeStatusLine(versionHome) {

package/dist/lib/daemon-ticks.js

@@ -162,8 +162,29 @@ export async function runActiveSessionsWarmTick(opts = {}) {
         console.log('active-sessions warm: idle (no recent reader), skipping gather');
         return { sessions: 0 };
     }
-    const r = await publishLocalActiveSessions({ gather: opts.gather, nowMs });
-    console.log(`active-sessions warm: ${r.sessions.length} session(s) published`);
+    // ONE gather per tick, then fold, then publish. The order is load-bearing:
+    // the publish's per-row merge reads the timeline cache, so folding first is
+    // what puts a CURRENT timeline on the row this tick writes to the journal
+    // rather than the previous tick's (PHNX-3939).
+    const gather = opts.gather ?? (async () => {
+        const { getActiveSessions } = await import('./session/active.js');
+        return getActiveSessions({ localOnly: true });
+    });
+    const gathered = await gather();
+    // Bounded so it can never own the tick: at most 8 sessions, and for the
+    // resumable harnesses only the bytes each transcript grew by. A failure here
+    // must not cost the publish.
+    const { runTimelinePassSync } = await import('./session/timeline-pass.js');
+    let timeline = { computed: 0, reused: 0, skipped: 0 };
+    try {
+        timeline = runTimelinePassSync({ sessions: gathered, nowMs });
+    }
+    catch (err) {
+        console.log(`active-sessions warm: timeline pass failed: ${err.message}`);
+    }
+    const r = await publishLocalActiveSessions({ gather: async () => gathered, nowMs });
+    console.log(`active-sessions warm: ${r.sessions.length} session(s) published; `
+        + `timeline ${timeline.computed} folded, ${timeline.reused} current, ${timeline.skipped} skipped`);
     return { sessions: r.sessions.length };
 }
 /**

package/dist/lib/devices/fleet-inventory.js

@@ -12,7 +12,7 @@ import { getAvailableResources, getVersionHomePath, isVersionIsolated, listInsta
 import { supports } from '../capabilities.js';
 import { checkVersionHookWiring } from '../hooks/install.js';
 import { getUserAgentsDir, getSystemAgentsDir, readMeta } from '../state.js';
-import { listNativeAccounts } from '../account-registry.js';
+import { findNativeAccountByIdentity } from '../account-registry.js';
 import { readRepoState } from '../git.js';
 import { ALL_AGENT_IDS, accountDisplayLabel, credentialPresence, getAccountInfo, supportsAccountInspection, } from '../agents.js';
 import { FLEET_RESOURCE_KINDS, } from './fleet-divergence.js';
@@ -46,9 +46,8 @@ export async function collectLocalFleetSignIn() {
                 signedIn = info.signedIn;
                 // Prefix the durable account name when this identity has been named.
                 const display = accountDisplayLabel(info);
-                const identityKey = info.accountKey ?? info.email?.toLowerCase();
-                const saved = identityKey ? listNativeAccounts(readMeta()).find(item => item.agent === agent && item.identityKey === identityKey) : undefined;
-                account = (saved ? `${saved.name} · ${display || saved.identityLabel || identityKey}` : display) || null;
+                const saved = findNativeAccountByIdentity(readMeta(), agent, info);
+                account = (saved ? `${saved.name} · ${display || saved.identityLabel || saved.identityKey}` : display) || null;
             }
             catch {
                 /* advisory only — treat as logged out, provability decided below */

package/dist/lib/devices/harness-inventory.js

@@ -18,7 +18,7 @@ import { ALL_AGENT_IDS, accountDisplayLabel, getAccountInfo, } from '../agents.j
 import { deriveUsageStatusFromSnapshot, getUsageInfoByIdentity, getUsageLookupKey, usageErrorForDisplay, } from '../accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { readMeta } from '../state.js';
-import { listNativeAccounts } from '../account-registry.js';
+import { findNativeAccountByIdentity } from '../account-registry.js';
 /**
  * Roll one usage snapshot into a {@link QuotaSummary}. Mirrors the blocking-window
  * selection of {@link deriveUsageStatusFromSnapshot} (the model-specific
@@ -118,7 +118,7 @@ export async function collectLocalHarnessInventory(opts) {
     const usageByKey = usageInputs.length
         ? (await getUsageInfoByIdentity(usageInputs, opts?.refresh ? { forceRefresh: true } : undefined)).usageByKey
         : new Map();
-    const savedNative = listNativeAccounts(readMeta());
+    const meta = readMeta();
     return pending.map(({ agent, version, info }) => {
         const key = getUsageLookupKey(info);
         const usage = key ? usageByKey.get(key) : undefined;
@@ -130,9 +130,8 @@ export async function collectLocalHarnessInventory(opts) {
         const signedIn = !!info?.signedIn;
         const { ready, reason } = computeReady(signedIn, quota);
         const display = info ? accountDisplayLabel(info) || null : null;
-        const identityKey = info?.accountKey ?? info?.email?.toLowerCase();
-        const saved = identityKey ? savedNative.find(item => item.agent === agent && item.identityKey === identityKey) : undefined;
-        const account = saved ? `${saved.name} · ${display || saved.identityLabel || identityKey}` : display;
+        const saved = findNativeAccountByIdentity(meta, agent, info);
+        const account = saved ? `${saved.name} · ${display || saved.identityLabel || saved.identityKey}` : display;
         return { agent, version, account, signedIn, quota, ready, reason };
     });
 }

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

@@ -0,0 +1,60 @@
+import { type ActivityEvent } from './activity.js';
+/** How often the stream falls back to a full directory stat sweep. */
+export declare const ACTIVITY_SWEEP_MS = 5000;
+/** Bytes behind the cursor re-verified before appended bytes are trusted. */
+export declare const ACTIVITY_ANCHOR_BYTES = 64;
+export interface ActivityStreamOptions {
+    /** Override the activity dir (tests). */
+    root?: string;
+    /**
+     * Newest bytes read from one file in one tick. A burst larger than this keeps
+     * only the tail, exactly as `readRecentActivity`'s bounded tail does.
+     */
+    maxBytesPerRead?: number;
+    /** Full stat sweep cadence, covering anything the directory watcher misses. */
+    sweepMs?: number;
+    /** Subscribe to directory change notifications (default true). */
+    watch?: boolean;
+}
+/**
+ * A cursor over the activity directory. Construct it at the moment the caller's
+ * activity cursor starts, then call {@link read} once per tick.
+ */
+export declare class ActivityStream {
+    private readonly dir;
+    private readonly maxBytesPerRead;
+    private readonly sweepMs;
+    private readonly cursors;
+    private readonly dirty;
+    private watcher?;
+    private watchRequested;
+    private lastSweepMs;
+    /** False during the opening scan, so it registers history without reading it. */
+    private started;
+    /** Bytes read from activity logs since construction. Observability + tests. */
+    bytesRead: number;
+    constructor(options?: ActivityStreamOptions);
+    /**
+     * Events appended since the last call, newest first, filtered to `sinceMs`
+     * inclusive — the same shape and order `readRecentActivity({ sinceMs })`
+     * returns for those events.
+     */
+    read(sinceMs: number, nowMs?: number): ActivityEvent[];
+    /** Release the directory watcher. Safe to call more than once. */
+    close(): void;
+    /** Which log names could have changed since the previous tick. */
+    private candidates;
+    /**
+     * Stat every log, marking the ones that could have changed. Opens nothing: a
+     * log the opening scan sees is registered past its own bytes, so history is
+     * never replayed onto the stream.
+     */
+    private sweep;
+    private statOf;
+    /** A cursor starting at a bounded tail of the file as it stands right now. */
+    private freshCursor;
+    /** Read and parse only the bytes appended to one log since its cursor. */
+    private readFile;
+    private readRange;
+    private armWatcher;
+}

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

@@ -0,0 +1,271 @@
+/**
+ * Incremental reader for the activity log directory.
+ *
+ * `readRecentActivity` answers "what happened since T?" by tailing and parsing
+ * every session log in the directory. That is the right shape for a one-shot
+ * `agents feed` render and the wrong shape for `agents feed watch`, which asks
+ * the same question twice a second for as long as a VS Code window is open: on
+ * a real operator box the directory holds 1,437 logs / 64 MB, so every tick
+ * re-read and re-parsed the whole corpus to emit, almost always, nothing.
+ *
+ * This reader keeps a per-file cursor instead. The opening scan opens no files
+ * at all — it records each log's size, inode, and mtime — so only bytes appended
+ * *after* the stream started are ever read. Steady-state cost is one `stat` per
+ * changed file plus a parse of exactly the appended bytes.
+ *
+ * The emitted events, their order, and the `sinceMs` filter match
+ * `readRecentActivity` for everything appended while the stream is open; the
+ * equivalence is pinned by `activity-stream.test.ts`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getActivityDir } from '../state.js';
+import { ACTIVITY_TAIL_BYTES, parseActivityLine } from './activity.js';
+/** How often the stream falls back to a full directory stat sweep. */
+export const ACTIVITY_SWEEP_MS = 5_000;
+/** Bytes behind the cursor re-verified before appended bytes are trusted. */
+export const ACTIVITY_ANCHOR_BYTES = 64;
+const NEWLINE = 0x0a;
+const EMPTY = Buffer.alloc(0);
+/** Could this file have changed since its cursor last looked? */
+function changed(cursor, stat) {
+    return stat.identity !== cursor.identity
+        || stat.size !== cursor.size
+        || stat.mtimeNs !== cursor.mtimeNs
+        || stat.ctimeNs !== cursor.ctimeNs;
+}
+/**
+ * A cursor over the activity directory. Construct it at the moment the caller's
+ * activity cursor starts, then call {@link read} once per tick.
+ */
+export class ActivityStream {
+    dir;
+    maxBytesPerRead;
+    sweepMs;
+    cursors = new Map();
+    dirty = new Set();
+    watcher;
+    watchRequested;
+    lastSweepMs = 0;
+    /** False during the opening scan, so it registers history without reading it. */
+    started = false;
+    /** Bytes read from activity logs since construction. Observability + tests. */
+    bytesRead = 0;
+    constructor(options = {}) {
+        this.dir = options.root ?? getActivityDir();
+        this.maxBytesPerRead = options.maxBytesPerRead ?? ACTIVITY_TAIL_BYTES;
+        this.sweepMs = options.sweepMs ?? ACTIVITY_SWEEP_MS;
+        this.watchRequested = options.watch ?? true;
+        this.sweep(Date.now());
+        this.armWatcher();
+    }
+    /**
+     * Events appended since the last call, newest first, filtered to `sinceMs`
+     * inclusive — the same shape and order `readRecentActivity({ sinceMs })`
+     * returns for those events.
+     */
+    read(sinceMs, nowMs = Date.now()) {
+        const out = [];
+        for (const name of this.candidates(nowMs)) {
+            for (const event of this.readFile(name)) {
+                const at = Date.parse(event.ts);
+                if (Number.isFinite(at) && at >= sinceMs)
+                    out.push(event);
+            }
+        }
+        out.sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
+        return out;
+    }
+    /** Release the directory watcher. Safe to call more than once. */
+    close() {
+        this.watchRequested = false;
+        this.watcher?.close();
+        this.watcher = undefined;
+    }
+    /** Which log names could have changed since the previous tick. */
+    candidates(nowMs) {
+        // A watcher that never armed (unsupported filesystem, or a directory that
+        // did not exist at construction) means every tick sweeps. That is the
+        // fallback: never a silent no-op that would drop events.
+        if (!this.watcher)
+            this.armWatcher();
+        if (!this.watcher || nowMs - this.lastSweepMs >= this.sweepMs)
+            this.sweep(nowMs);
+        const names = [...this.dirty];
+        this.dirty.clear();
+        return names;
+    }
+    /**
+     * Stat every log, marking the ones that could have changed. Opens nothing: a
+     * log the opening scan sees is registered past its own bytes, so history is
+     * never replayed onto the stream.
+     */
+    sweep(nowMs) {
+        this.lastSweepMs = nowMs;
+        let names;
+        try {
+            names = fs.readdirSync(this.dir).filter((name) => name.endsWith('.jsonl'));
+        }
+        catch {
+            return; // The directory appears with the first logged event.
+        }
+        const seen = new Set();
+        for (const name of names) {
+            seen.add(name);
+            const stat = this.statOf(name);
+            if (!stat)
+                continue;
+            const cursor = this.cursors.get(name);
+            if (!cursor) {
+                // A log first seen after the opening scan is new work: left
+                // unregistered so `readFile` opens it from a bounded tail.
+                if (this.started)
+                    this.dirty.add(name);
+                else
+                    this.cursors.set(name, {
+                        identity: stat.identity, offset: stat.size, partial: EMPTY, partialIsFragment: false,
+                        anchor: EMPTY, size: stat.size, mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs,
+                    });
+                continue;
+            }
+            if (changed(cursor, stat))
+                this.dirty.add(name);
+        }
+        // A cursor is dropped only when its log is gone. There is deliberately no
+        // size cap: the map cannot outgrow the directory this sweep already had to
+        // enumerate, so a cap bounds nothing the readdir does not — while dropping
+        // a live log's cursor would re-register it as new work on the next sweep
+        // and replay a bounded tail of it onto the stream as duplicates.
+        for (const name of [...this.cursors.keys()])
+            if (!seen.has(name))
+                this.cursors.delete(name);
+        this.started = true;
+    }
+    statOf(name) {
+        try {
+            const st = fs.statSync(path.join(this.dir, name), { bigint: true });
+            return {
+                identity: `${st.dev}:${st.ino}`,
+                size: Number(st.size),
+                mtimeNs: Number(st.mtimeNs),
+                ctimeNs: Number(st.ctimeNs),
+            };
+        }
+        catch {
+            return undefined; // Deleted between readdir and stat.
+        }
+    }
+    /** A cursor starting at a bounded tail of the file as it stands right now. */
+    freshCursor(stat) {
+        const offset = Math.max(0, stat.size - this.maxBytesPerRead);
+        return {
+            identity: stat.identity, offset, partial: EMPTY, partialIsFragment: offset > 0,
+            anchor: EMPTY, size: stat.size, mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs,
+        };
+    }
+    /** Read and parse only the bytes appended to one log since its cursor. */
+    readFile(name, restarted = false) {
+        const stat = this.statOf(name);
+        if (!stat) {
+            this.cursors.delete(name);
+            return [];
+        }
+        let cursor = this.cursors.get(name);
+        // Unseen, replaced, truncated, or rewritten in place at the same length:
+        // restart from a bounded tail of the file as it now stands. The caller's
+        // `sinceMs` drops whatever predates the stream.
+        //
+        // The same-length case is why ctime is tracked. Growth is caught by the
+        // 64-byte anchor and a shrink by the offset compare, but a rewrite that
+        // lands on exactly the previous size moves neither, and the early return
+        // below would otherwise retire the file for good with content unread.
+        if (!cursor || cursor.identity !== stat.identity || stat.size < cursor.offset
+            || (stat.size === cursor.size && stat.ctimeNs !== cursor.ctimeNs)) {
+            cursor = this.freshCursor(stat);
+            this.cursors.set(name, cursor);
+        }
+        cursor.size = stat.size;
+        cursor.mtimeNs = stat.mtimeNs;
+        cursor.ctimeNs = stat.ctimeNs;
+        if (stat.size <= cursor.offset)
+            return [];
+        // A burst larger than the budget keeps the newest bytes; the skipped span is
+        // exactly what the bounded-tail reader would have dropped as well.
+        const start = Math.max(cursor.offset, stat.size - this.maxBytesPerRead);
+        if (start > cursor.offset) {
+            cursor.partial = EMPTY;
+            cursor.partialIsFragment = true;
+            cursor.anchor = EMPTY;
+        }
+        const verify = Math.min(cursor.anchor.length, start);
+        const buf = this.readRange(name, start - verify, stat.size - start + verify);
+        if (buf === undefined)
+            return []; // Transient I/O error: retry next tick.
+        if (verify > 0 && !buf.subarray(0, verify).equals(cursor.anchor.subarray(cursor.anchor.length - verify))) {
+            // The bytes behind the cursor changed, so this file was rewritten rather
+            // than appended to. Restart it once from a bounded tail.
+            if (restarted)
+                return [];
+            this.cursors.delete(name);
+            return this.readFile(name, true);
+        }
+        const fresh = buf.subarray(verify);
+        cursor.offset = stat.size;
+        cursor.anchor = Buffer.concat([cursor.anchor, fresh]).subarray(-ACTIVITY_ANCHOR_BYTES);
+        const chunk = Buffer.concat([cursor.partial, fresh]);
+        const fragment = cursor.partialIsFragment;
+        const end = chunk.lastIndexOf(NEWLINE);
+        // Hold an unterminated trailing line: the writer appends whole
+        // newline-terminated records (`appendActivityEvent`), so a tail without a
+        // newline is a write in progress and completes on a later tick.
+        cursor.partial = end < 0 ? chunk : chunk.subarray(end + 1);
+        cursor.partialIsFragment = end < 0 ? fragment : false;
+        if (end < 0)
+            return [];
+        const lines = chunk.subarray(0, end).toString('utf-8').split('\n');
+        // A range that began mid-file starts inside a record; that leading fragment
+        // is not one, exactly as the bounded-tail reader drops it.
+        if (fragment)
+            lines.shift();
+        const events = [];
+        for (const line of lines) {
+            const event = parseActivityLine(line);
+            if (event)
+                events.push(event);
+        }
+        return events;
+    }
+    readRange(name, start, length) {
+        let fd;
+        try {
+            fd = fs.openSync(path.join(this.dir, name), 'r');
+            const buf = Buffer.allocUnsafe(length);
+            const read = fs.readSync(fd, buf, 0, length, start);
+            this.bytesRead += read;
+            return buf.subarray(0, read);
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+    }
+    armWatcher() {
+        if (!this.watchRequested || this.watcher)
+            return;
+        try {
+            this.watcher = fs.watch(this.dir, (_event, name) => {
+                if (typeof name === 'string' && name.endsWith('.jsonl'))
+                    this.dirty.add(name);
+            });
+            // A watch error (the directory is removed) degrades to sweeping rather
+            // than taking down the watcher process.
+            this.watcher.on('error', () => { this.watcher?.close(); this.watcher = undefined; });
+        }
+        catch {
+            this.watcher = undefined;
+        }
+    }
+}

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

@@ -129,6 +129,13 @@ export declare function appendActivityEvent(event: Omit<ActivityEvent, 'v' | 'ti
     v?: number;
     tier?: ActivityTier;
 }, root?: string): void;
+/**
+ * Parse one activity log line. Tolerant by design: a blank, corrupt, or
+ * half-written line is skipped rather than failing the whole read.
+ */
+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 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. */