@phnx-labs/agents-cli 1.22.83 → 1.22.84

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 1.22.84
+
+- **`agents feed watch` is cheap enough to leave running (PHNX-3939).** The watcher
+  cost ~42% of a core steadily on a box with 1,437 activity logs / 64 MB, because
+  every 500 ms tick re-read and re-parsed the whole activity corpus and re-read
+  every row's block, resolution, and PR status. It now keeps a per-file cursor and
+  reads only the bytes appended since the last tick (`ActivityStream`), and
+  reconciles attention only when something announced a change — a block or
+  resolution written under the feed dir, watched directly — or when the 45 s
+  PR-status TTL has expired. Measured on the same box over 5 minutes, steady
+  state: `--local` **41.9% → 0.31% CPU** (RSS 313 MB → 140 MB) and the full
+  13-peer fleet fan-out **50.0% → 0.37% CPU** (RSS 606 MB → 143 MB), with an
+  identical envelope stream. Source: `cli/src/lib/feed/activity-stream.ts`,
+  `cli/src/lib/feed/watch.ts`.
+
+- **A fleet peer that cannot be reached no longer gets a fresh `ssh` every few
+  seconds (PHNX-3939).** `agents feed watch` and `agents sessions watch` respawned
+  each peer's `--local` subscription on a bare 2 s timer with the child's stderr
+  discarded, so an offline box burned a ConnectTimeout-plus-2s cycle for the whole
+  life of the watcher and reported only `ssh exited 255`. Both fan-outs now share
+  one implementation with per-peer exponential backoff (2 s doubling to a 60 s
+  cap, reset on a healthy protocol event), the peer's own stderr surfaced as the
+  `unavailable` reason, and a peer parked after three consecutive failed spawns
+  until the device registry changes or the capped delay elapses. Source:
+  `cli/src/lib/session/remote/peer-stream.ts`.
+
+- **`agents accounts connect` refuses on a worker before any install or browser login (PHNX-3940).** A worker never runs an interactive OAuth flow (credential-management.md invariant 7). On a non-headed device (`worker` or unmarked), connect throws and does nothing — no slot, no install, no browser. Add the account on a personal/desktop box; workers are provisioned from the durable credential. Source: `cli/src/lib/accounts/connect.ts`.
+
+- **Every session row carries the request the agent was given and a timeline of what it did (PHNX-3939).** `agents sessions --active --json`, `sessions watch --json`, `feed watch --json`, history rows and the fleet session mirror gain three optional fields: `request` (the LATEST genuine user turn, tidied — the user's own sentence, with screenshot/clip paths, `@dir` mentions and pasted terminal echo pulled out into `attachments` / `pastedLines`, never rewritten), `timeline` (narration-anchored steps — one per line the agent said, with the tool calls under it folded into per-verb counts, failures, blocked calls and milestones; the last 8 in full plus a counter for everything older), and `files` (the paths the session created / modified / deleted, from the harness's own ledger where it keeps one). The fold is deterministic and needs no model; the optional summarizer now takes the narration as input and stays off by default. Computed by the daemon inside its existing reader-gated 15s tick, reading only the bytes each transcript grew by, and cached in the new stamp-validated `session_timelines` table — zero cost on the request path. Source: `cli/src/lib/session/timeline.ts`, `cli/src/lib/session/timeline-pass.ts`, `cli/src/lib/session/db.ts`.
+- **A `/model` echo or a skill body can no longer become a session's title (PHNX-3939).** `extractSessionTopic` consulted a shorter skip list than `cleanFirstUserMessage`, so harness scaffolding — `<local-command-stdout>`, `Base directory for this skill:`, hook feedback, `<hook_result>`, `<notification>` — became a session's topic and then its displayed name. The two lists are now one, and the row title / `userPromptClean` are derived from the raw latest genuine user turn (with the row's attachments in hand) instead of the already-collapsed topic. Source: `cli/src/lib/session/prompt.ts`, `cli/src/lib/session/active.ts`.
+- **`agents sessions trace <id> --steps` prints the step list the sidebar shows.** The same fold as the session row, as text: `NN  +MMs  source  headline  · 6 run · 2 blocked · worktree created`, with a totals footer. The CLI door to the timeline for an agent working without the extension. Source: `cli/src/commands/sessions-trace.ts`.
+- **The parser keeps the per-tool label every harness writes (PHNX-3939).** Claude's Bash `input.description`, Kimi's `tool.call.description`, OpenCode's `state.input.description` / `state.title` and Codex's parsed command now ride the normalized `SessionEvent` as `label`, so a live row's now-line reads as the sentence the model wrote for it instead of a re-derived command summary. Codex additionally gains a reader for its typed `item_completed` stream (`AgentMessage` phase, `parsed_cmd`, `FileChange`, `Extension`, `SubAgentActivity`, `ImageView`, `ContextCompaction`) — kept separate from `parseCodexContent` because the two describe the same turn, and an unknown item type folds to a counted call rather than throwing. Claude permission/hook denials are now distinguished from command failures (`blocked` vs `failed`). Source: `cli/src/lib/session/parse.ts`.
+- **`sessions watch` history rows cover every transcript-writing harness.** `readPreviousSessionsForWatch` queried only claude/codex/muse/opencode, so a Kimi, Grok, Cursor or Droid session never appeared as a Previous row. Source: `cli/src/lib/session/remote/watch.ts`.
+- **The timeline redacts and de-escapes the transcript text it ships.** `projectTimeline` is the single place folded text leaves the fold, so step headlines, the now-line and milestone marks now run through `redactSecrets` (on by default; `sessions trace --no-redact` is the only opt-out) and always through `sanitizeForTerminal`. Without it a Bash call with no `description` fell back to raw command text, so a pasted token rode the session row into the git-tracked `~/.agents/devices/<device>/daemon-state.json`, and a transcript carrying ESC sequences could clear the operator's screen on `sessions trace --steps`. `--steps` now honours the command's own `--redact` default, and `sanitizeEvent` covers the new `label` and `phase` fields. Source: `cli/src/lib/session/timeline.ts`, `cli/src/lib/session/parse.ts`, `cli/src/commands/sessions-trace.ts`.
+- **A 4-16 MiB transcript on a non-resumable harness gets a timeline.** Whole-file eligibility was gated on the per-session allowance, capped at 4 MiB however idle the tick was, while `unavailable` only fired above 16 MiB — so a kimi/grok/gemini/cursor/opencode/droid session in that band got no row at all (not `ready`, not `partial`, not `unavailable`) and was counted `reused`, leaving the daemon log reading healthy. It is now gated on what the tick can actually afford, the byte budget is debited by the bytes each branch really reads (the whole file for a whole-file re-parse, not its growth delta), and a session that genuinely does not fit writes a `partial` row naming the budget. A per-session fold that throws is logged and counted `skipped` instead of swallowed. Source: `cli/src/lib/session/timeline-pass.ts`.
+- **Cursor and Droid keep their per-call label too.** Both write the same human one-liner through the shared Anthropic-message parser — Cursor as `description`, Droid as `summary` — and neither reached `SessionEvent.label`, so a Droid `Execute{command:"ls -la", summary:"List files"}` rendered its now-line as `ls -la` while the equivalent Claude call read `List files`. Source: `cli/src/lib/session/parse.ts`.
+- **A tool cut short with Ctrl-C counts as blocked, not failed.** `toolUseResult.interrupted` joins `toolDenialKind` as an input to `blocked`, so interrupting an agent no longer inflates its failure count. Source: `cli/src/lib/session/parse.ts`.
+- **`now` ships only on the live step, and `ready` is never an empty step list.** `attachTool` sets the now-line on every step as it folds; every finished step kept a stale one, so a consumer rendered a now-line on completed work at ~700 bytes a row. A fold that produced no step now reports its state honestly instead of `ready` with nothing in it. The fleet mirror also carries `mix` and `live` through the consume path, which rebuilt each step from a field list that dropped both while keeping `now`. Source: `cli/src/lib/session/timeline.ts`, `cli/src/lib/session/mirror.ts`.
+
 ## 1.22.83
 
 - **The Claude status line shows the registered account NAME (PHNX-3987).** A login named with `agents accounts` (`work`, `dev`, …) now renders that name between the host and the model — `yosemite · work · Fable 5.1 · …` — which is what tells several same-harness logins apart at a glance; an unnamed login keeps the email label. The lookup is the one `agents view` and the device inventories already use, lifted into `findNativeAccountByIdentity` so the three copies share it. Source: `cli/src/lib/claude-statusline.ts`, `cli/src/lib/account-registry.ts`.

package/dist/commands/accounts.js

@@ -535,7 +535,7 @@ export function registerAccountsCommand(program) {
 agents accounts connect codex personal
 agents accounts connect claude work   # again → reuses work's home, fails closed on a different identity
 agents run claude --account work`,
-        notes: `Each NEW account gets a fresh opaque installation label and its own isolated home, so ten accounts can share the same upstream release while keeping separate logins. Connect installs the current release even when it is already installed under another label, then launches the harness's native login there — the OAuth credential is never copied or fleet-synced. Reconnecting an existing account by name reuses its home and refuses to overwrite a home now signed in as a different identity. Supported for version-scoped, isolable harnesses (${connectSupportedList()}); others fail with a clear reason. Provider API-key/token accounts use 'agents accounts add' instead.`,
+        notes: `Each NEW account gets a fresh opaque installation label and its own isolated home, so ten accounts can share the same upstream release while keeping separate logins. Connect installs the current release even when it is already installed under another label, then launches the harness's native login there — the OAuth credential is never copied or fleet-synced. Reconnecting an existing account by name reuses its home and refuses to overwrite a home now signed in as a different identity. Headed devices only: on a worker connect refuses before any slot, install, or browser — add the account on a personal/desktop box and provision workers from the durable credential. Supported for version-scoped, isolable harnesses (${connectSupportedList()}); others fail with a clear reason. Provider API-key/token accounts use 'agents accounts add' instead.`,
     });
     accounts.command('add <name>')
         .description('Add a durable API key, setup token, or bearer token')

package/dist/commands/sessions-trace.d.ts

@@ -1,4 +1,5 @@
 import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
 import type { SessionTrajectory } from '../lib/session/trajectory.js';
 import type { TrajectoryComparison, TrajectoryDivergence, TrajectorySummary } from '../lib/session/trajectory-compare.js';
 import type { TrajectoryStep } from '../lib/session/trajectory.js';
@@ -50,6 +51,7 @@ interface TraceOptions {
     output?: string;
     open?: boolean;
     errorsOnly?: boolean;
+    steps?: boolean;
     redact?: boolean;
     all?: boolean;
     since?: string;
@@ -73,6 +75,15 @@ export declare function chooseFormat(options: TraceOptions, isTTY: boolean): Ren
  * clear message. Pure, so the boundaries are unit-tested without the command.
  */
 export declare function decideTraceLayout(options: Pick<TraceOptions, 'tree' | 'compare'>, selectorCount: number, resolvedCount: number): 'single' | 'compare' | 'lineage';
+/**
+ * Render one session's narration-anchored step list — the same fold the daemon
+ * caches and the sidebar renders, computed here from the transcript so the
+ * command works for any session, live or closed, cached or not.
+ */
+export declare function renderSessionSteps(session: SessionMeta, options?: {
+    redact?: boolean;
+    knownSecrets?: readonly string[];
+}): string;
 /** Attach the trace behaviour to a command node (canonical or top-level alias). */
 export declare function configureTraceCommand(cmd: Command): Command;
 /** Canonical `agents sessions trace <selectors...>`. */

package/dist/commands/sessions-trace.js

@@ -23,6 +23,8 @@ import { knownSecretValuesFromEnv } from '../lib/redact.js';
 import { getCacheDir } from '../lib/state.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { parseSession } from '../lib/session/parse.js';
+import { foldTimeline, projectSessionFiles, projectTimeline } from '../lib/session/timeline.js';
+import { parseTimelineEvents } from '../lib/session/timeline-pass.js';
 import { buildTrajectory } from '../lib/session/trajectory.js';
 import { diffTrajectories } from '../lib/session/trajectory-compare.js';
 import { buildLineage } from '../lib/session/trajectory-lineage.js';
@@ -134,6 +136,53 @@ export function decideTraceLayout(options, selectorCount, resolvedCount) {
     }
     return 'single';
 }
+/** One step's counters, rendered as the sidebar renders them: `6 run · 2 blocked`. */
+function stepDetail(step) {
+    const mix = Object.entries(step.mix ?? {})
+        .filter(([, count]) => (count ?? 0) > 0)
+        .sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))
+        .map(([verb, count]) => `${count} ${verb}`);
+    return [
+        ...mix,
+        step.failed ? `${step.failed} failed` : '',
+        step.blocked ? `${step.blocked} blocked` : '',
+        ...(step.marks ?? []),
+    ].filter(Boolean).join(' · ');
+}
+/**
+ * Render one session's narration-anchored step list — the same fold the daemon
+ * caches and the sidebar renders, computed here from the transcript so the
+ * command works for any session, live or closed, cached or not.
+ */
+export function renderSessionSteps(session, options = {}) {
+    const state = foldTimeline(parseTimelineEvents(session.filePath, session.agent), undefined, {});
+    const timeline = projectTimeline(state, undefined, state.steps.length, options);
+    if (!timeline.steps.length) {
+        return `No steps folded for ${session.shortId || session.id}` +
+            `${timeline.reason ? ` — ${timeline.reason}` : ''}\n`;
+    }
+    const startMs = state.firstMs ?? Date.parse(timeline.steps[0].at);
+    const lines = timeline.steps.map((step, index) => {
+        const offsetS = Math.max(0, Math.round((Date.parse(step.at) - startMs) / 1000));
+        const detail = stepDetail(step);
+        return [
+            String(index + 1).padStart(2),
+            `+${offsetS}s`.padStart(7),
+            step.source.slice(0, 4).padEnd(4),
+            step.text,
+            detail ? `· ${detail}` : '',
+        ].filter(Boolean).join('  ');
+    });
+    const files = projectSessionFiles(state);
+    const footer = [
+        `${timeline.steps.length} steps`,
+        `${timeline.tools} tools`,
+        timeline.failed ? `${timeline.failed} failed` : '',
+        timeline.blocked ? `${timeline.blocked} blocked` : '',
+        files ? `${files.total} file${files.total === 1 ? '' : 's'} changed` : '',
+    ].filter(Boolean).join(' · ');
+    return `${lines.join('\n')}\n\n${footer}\n`;
+}
 /** Attach the trace behaviour to a command node (canonical or top-level alias). */
 export function configureTraceCommand(cmd) {
     cmd
@@ -144,6 +193,7 @@ export function configureTraceCommand(cmd) {
         .option('-o, --output <path>', 'Write the rendering to a path instead of opening/printing')
         .option('--no-open', 'Do not open the HTML; print its path instead')
         .option('--errors-only', 'Collapse the text trajectory to error steps and their neighbours')
+        .option('--steps', 'Print the narration-anchored step list the sidebar shows (the same fold as the session row)')
         .option('--compare', 'Force the compare layout for exactly two selectors (this is also the default for two)')
         .option('--tree', 'Render the lineage of one session — it and every session it spawned')
         .option('--no-redact', 'Local-only: skip secret redaction of derived labels (never for a shared file)')
@@ -161,6 +211,9 @@ agents sessions trace a1b2c3d4 --text
 # Just the failures and their neighbours — for a triaging agent
 agents sessions trace a1b2c3d4 --text --errors-only
 
+# What the agent said it was doing, step by step — the sidebar's timeline as text
+agents sessions trace a1b2c3d4 --steps
+
 # The stable JSON envelope for the AGI EXT Fleet panel or a tool
 agents sessions trace a1b2c3d4 --json
 
@@ -223,6 +276,9 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
         // count — a single content-search selector matching two sessions must NOT
         // silently become a compare. All the fail-loud boundaries live in the pure
         // decideTraceLayout so they are unit-tested (see sessions-trace.test.ts).
+        if (options.steps && selectors.length > 1) {
+            throw new Error('--steps renders one session\'s step list; pass a single selector.');
+        }
         const layout = decideTraceLayout(options, selectors.length, sessions.length);
         const redact = options.redact !== false;
         const knownSecrets = redact ? knownSecretValuesFromEnv() : undefined;
@@ -333,6 +389,21 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
         }
         // One selector — the single-session trajectory.
         const session = sessions[0];
+        // --steps is the CLI door to the timeline fold the sidebar renders, so an
+        // agent can read what a session DID without the extension (PHNX-3939). It is
+        // a different model from the trajectory (narration beats, not tool steps),
+        // so it short-circuits before buildTrajectory rather than reshaping it.
+        if (options.steps) {
+            const out = renderSessionSteps(session, { redact, knownSecrets });
+            if (options.output) {
+                fs.writeFileSync(options.output, out, { mode: 0o600 });
+                process.stderr.write(chalk.green(`Wrote step list to ${options.output}\n`));
+            }
+            else {
+                process.stdout.write(out);
+            }
+            return;
+        }
         const model = buildOne(session);
         if (format === 'json') {
             const out = JSON.stringify(buildTraceEnvelope([model]), null, 2) + '\n';

package/dist/lib/accounts/connect.d.ts

@@ -18,6 +18,12 @@ export declare function connectSupported(agent: AgentId): boolean;
  */
 export declare function connectRefusal(agent: AgentId): string | null;
 export declare function assertConnectSupported(agent: AgentId): void;
+/**
+ * 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 declare function connectWorkerRefusal(agent: AgentId, name?: string): string | null;
 export declare function loginInvocation(agent: AgentId): LoginInvocation;
 /**
  * Mint a fresh, opaque installation slot. `acct-<hex>` — alnum + hyphen only, so

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/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/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;
+}