metaFromEvents is gone: nothing rebuilt an agent meta from a whole log (#1039) (#1696)

The export had no production caller — the meta is stored beside the log and refined per
appended event — and it anchored updatedAt to startedAt on replay, so any future caller would
have inherited a wrong last-touched time. The tests that used it as a fixture now fold their
base through a real store, the way a live run does.

Author: suleimansh

packages/framework/src/cloud-session-link.test.ts

@@ -2,10 +2,26 @@ import { strict as assert } from 'node:assert'
 import { test } from 'node:test'
 import { CloudDriver } from './driver/cloud.js'
 import { createDriverEventHandler, emitSessionStart } from './agent-telemetry.js'
-import { metaFromEvents } from './store/index.js'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { AgentStore, type AgentMeta } from './store/index.js'
 import { CLAUDE_CODE_SESSION_LINK } from './session-link.js'
 import type { FrameworkEvent } from './events.js'
 
+/** The meta after `events`, folded the way a live run folds them: appended to a real store. */
+async function foldLive(events: readonly FrameworkEvent[], at: string): Promise<AgentMeta> {
+  const cwd = await mkdtemp(join(tmpdir(), 'tf-session-link-'))
+  try {
+    const store = await AgentStore.open(cwd, { now: at, clock: () => at })
+    for (const event of events) await store.append(event)
+    await store.close()
+    return store.snapshot()
+  } finally {
+    await rm(cwd, { recursive: true, force: true })
+  }
+}
+
 // #1317: a web agent's meta dead-ended on the generic https://claude.ai/code — recorded by the
 // opening `session` event before any session existed — even though the CloudDriver had the real
 // URL in hand. This wires the real driver through the real telemetry into the real meta fold,
@@ -40,7 +56,7 @@ test('a cloud run meta ends with the real session URL, not the generic entry poi
   const session = await driver.start({ cwd: '/repo', onEvent: handler.onDriverEvent })
   await session.prompt('go')
 
-  const meta = metaFromEvents(events, '2026-01-01T00:00:00.000Z')
+  const meta = await foldLive(events, '2026-01-01T00:00:00.000Z')
   assert.equal(meta.sessionLink, URL, 'the meta must carry the deep link once the hand-off knows it')
   // The opening event still honestly says what was known before the session existed.
   const opening = events.find(e => e.kind === 'session')

packages/framework/src/store/agent-store.SPEC.md

@@ -32,7 +32,7 @@ The user opens an agent and sees a header: what it was asked for, which coding a
 
 #### Business logic
 
-An agent's every fact arrives as an event appended to its event log, and the agent meta is the running fold of those events. Folding is the same operation whether it happens as an event is appended or by replaying a whole log from scratch, so a record rebuilt after a restart says exactly what the live one said.
+An agent's every fact arrives as an event appended to its event log, and the agent meta is the running fold of those events: each appended event refines the record, and the record is stored beside the log rather than rebuilt from it.
 
 The agent meta carries: whether the agent is running, done, stopped or failed; its id and its start and last-update times; the process and host that own it; what it was asked for; which driver and workspace it uses; the wrapped CLI's session id, session link and the agent-chosen session name; the branch its work is on; the ticket it implements, when the framework picked one; the pull request opened for it; whether it signalled ready for merge; what its handoff is armed to do and how that handoff reported back; the gate it is parked on; whether it has settled on the user; for a cloud session, whether the browser bridge holds a question it is parked on, and whether another machine's daemon started the agent — both marked by the daemon on the way to the dashboard, never stored; the port its browser preview listens on; its run target and, for a relayed agent, the device label; whether it started as a build or a direct prompt; the model the current leg runs; and, for a cloud session, the hand-off anchor commit.
 

packages/framework/src/store/agent-store.test.SPEC.md

@@ -11,7 +11,6 @@ What the tests cover: how an agent's record is written, summarized, archived and
 
 **Folding events into the agent meta**
 
-- Rebuilding the agent meta by replaying a whole log yields the same summary as folding events as they are appended.
 - A later request refines the seeded one.
 - The model is recorded per leg: the latest leg wins, and a leg that reports no model leaves it unknown rather than inheriting.
 - Handoff arming is mirrored, including whether merge is armed, without padding fields the arming never stated.

packages/framework/src/store/agent-store.test.ts

@@ -5,7 +5,6 @@ import { hostname } from 'node:os'
 import {
   AgentStore,
   applyEventToMeta,
-  metaFromEvents,
   listAgents,
   readLiveMeta,
   readLiveMetas,
@@ -73,6 +72,16 @@ const RUN: FrameworkEvent[] = [
   { kind: 'end', ok: true },
 ]
 
+/** The meta after `events`, folded the way a live run folds them: appended to a real store. */
+async function foldLive(events: readonly FrameworkEvent[], at: string): Promise<AgentMeta> {
+  const store = await AgentStore.open(CWD, { fs: memFs(), now: at, clock: () => at })
+  for (const event of events) await store.append(event)
+  return store.snapshot()
+}
+
+/** A run three events in: opened and working, nothing decided yet. What the fold tests refine from. */
+const BASE = await foldLive(RUN.slice(0, 3), AT)
+
 test('fresh open truncates the log and writes an initial meta snapshot', async () => {
   const fs = memFs({ [EVENTS]: 'stale\n' })
   const store = await AgentStore.open(CWD, { fs, fresh: true, now: AT })
@@ -155,16 +164,8 @@ test('loadEvents on a never-run workspace yields an empty array', async () => {
   assert.deepEqual(await store.loadEvents(), [])
 })
 
-test('metaFromEvents reconstructs the same snapshot as live appends', async () => {
-  const meta = metaFromEvents(RUN, AT)
-  assert.equal(meta.intent, 'a blog with comments')
-  assert.equal(meta.status, 'done')
-  assert.equal(meta.startedAt, AT)
-})
-
 test('applyEventToMeta records the model per leg — the latest session event wins, an unrecorded one clears it (#1438)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  const first = applyEventToMeta(base, { kind: 'session', driver: 'claude', workspace: '/w', fake: false, model: 'fable' }, AT)
+  const first = applyEventToMeta(BASE, { kind: 'session', driver: 'claude', workspace: '/w', fake: false, model: 'fable' }, AT)
   assert.equal(first.model, 'fable')
   // A continuation leg may run a different model: fold, don't pin.
   const second = applyEventToMeta(first, { kind: 'session', driver: 'claude', workspace: '/w', fake: false, model: 'sonnet' }, AT)
@@ -175,32 +176,29 @@ test('applyEventToMeta records the model per leg — the latest session event wi
 })
 
 test('applyEventToMeta mirrors the merge arming onto the meta, so a mid-run tab can read it (#1382)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  const armed = applyEventToMeta(base, { kind: 'handoff-armed', push: true, pr: true, merge: true }, AT)
+  const armed = applyEventToMeta(BASE, { kind: 'handoff-armed', push: true, pr: true, merge: true }, AT)
   assert.deepEqual(armed.handoff, { push: true, pr: true, merge: true })
   // A pre-#1382 event has no merge field: the mirror stays shaped like the event, not padded.
-  const old = applyEventToMeta(base, { kind: 'handoff-armed', push: true, pr: false }, AT)
+  const old = applyEventToMeta(BASE, { kind: 'handoff-armed', push: true, pr: false }, AT)
   assert.deepEqual(old.handoff, { push: true, pr: false })
 })
 
 test('applyEventToMeta folds the handoff report onto the meta, so list surfaces can tell publishing from done (#1455)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.handoffReport, undefined, 'no report until the epilogue speaks')
-  const done = applyEventToMeta(base, { kind: 'handoff', outcome: 'done', pushed: true }, AT)
+  assert.equal(BASE.handoffReport, undefined, 'no report until the epilogue speaks')
+  const done = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'done', pushed: true }, AT)
   assert.equal(done.handoffReport, 'done')
-  const skipped = applyEventToMeta(base, { kind: 'handoff', outcome: 'skipped', reason: 'not-armed' }, AT)
+  const skipped = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'skipped', reason: 'not-armed' }, AT)
   assert.equal(skipped.handoffReport, 'skipped')
-  const failed = applyEventToMeta(base, { kind: 'handoff', outcome: 'failed', step: 'push', error: 'boom' }, AT)
+  const failed = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'failed', step: 'push', error: 'boom' }, AT)
   assert.equal(failed.handoffReport, 'failed')
 })
 
 test('applyEventToMeta folds the skip reason onto the meta, so the sweep can free a dead claim (#1583)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.handoffSkip, undefined)
-  const skipped = applyEventToMeta(base, { kind: 'handoff', outcome: 'skipped', reason: 'no-commits' }, AT)
+  assert.equal(BASE.handoffSkip, undefined)
+  const skipped = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'skipped', reason: 'no-commits' }, AT)
   assert.equal(skipped.handoffSkip, 'no-commits')
   // A handoff that ran carries no skip: the field means "why nothing happened", nothing else.
-  const done = applyEventToMeta(base, { kind: 'handoff', outcome: 'done', pushed: true }, AT)
+  const done = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'done', pushed: true }, AT)
   assert.equal(done.handoffSkip, undefined)
   // And a later leg that published clears a stale skip — a resumed run's second handoff can
   // publish after its first skipped, and the release must not act on leg one's reason.
@@ -209,34 +207,30 @@ test('applyEventToMeta folds the skip reason onto the meta, so the sweep can fre
 })
 
 test('applyEventToMeta folds the merge outcome onto the meta, so the CI watch can find its PRs (#1418)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.mergeOutcome, undefined)
-  const watched = applyEventToMeta(base, { kind: 'handoff', outcome: 'done', pushed: true, merge: { outcome: 'watched' } }, AT)
+  assert.equal(BASE.mergeOutcome, undefined)
+  const watched = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'done', pushed: true, merge: { outcome: 'watched' } }, AT)
   assert.equal(watched.mergeOutcome, 'watched')
   // The already-open skip carries a merge too (#1216): a rerun finding its predecessor's PR.
-  const armed = applyEventToMeta(base, { kind: 'handoff', outcome: 'skipped', reason: 'already-open', merge: { outcome: 'auto-armed' } }, AT)
+  const armed = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'skipped', reason: 'already-open', merge: { outcome: 'auto-armed' } }, AT)
   assert.equal(armed.mergeOutcome, 'auto-armed')
-  const noMerge = applyEventToMeta(base, { kind: 'handoff', outcome: 'done', pushed: true }, AT)
+  const noMerge = applyEventToMeta(BASE, { kind: 'handoff', outcome: 'done', pushed: true }, AT)
   assert.equal(noMerge.mergeOutcome, undefined, 'a handoff without a merge half folds nothing')
 })
 
 test('applyEventToMeta marks a thrown run as failed', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  const failed = applyEventToMeta(base, { kind: 'end', ok: false, detail: 'boom' }, AT)
+  const failed = applyEventToMeta(BASE, { kind: 'end', ok: false, detail: 'boom' }, AT)
   assert.equal(failed.status, 'failed')
 })
 
 test('applyEventToMeta marks a user-stopped run as stopped, not failed (#218)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  const stopped = applyEventToMeta(base, { kind: 'end', ok: false, stopped: true }, AT)
+  const stopped = applyEventToMeta(BASE, { kind: 'end', ok: false, stopped: true }, AT)
   assert.equal(stopped.status, 'stopped')
 })
 
 test('applyEventToMeta tracks whether the run is working or parked on the user (#785)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.settledAt, undefined, 'a working run is not parked')
+  assert.equal(BASE.settledAt, undefined, 'a working run is not parked')
 
-  const parked = applyEventToMeta(base, { kind: 'settled' }, AT)
+  const parked = applyEventToMeta(BASE, { kind: 'settled' }, AT)
   assert.equal(parked.settledAt, AT)
   assert.equal(parked.status, 'running', 'still live: it holds the project and takes messages')
 
@@ -245,26 +239,24 @@ test('applyEventToMeta tracks whether the run is working or parked on the user (
   assert.equal(working.settledAt, undefined)
 
   // An agent that has ended is not waiting on anyone.
-  const ended = applyEventToMeta(applyEventToMeta(base, { kind: 'settled' }, AT), { kind: 'end', ok: true }, AT)
+  const ended = applyEventToMeta(applyEventToMeta(BASE, { kind: 'settled' }, AT), { kind: 'end', ok: true }, AT)
   assert.equal(ended.settledAt, undefined)
   assert.equal(ended.status, 'done')
 })
 
 test('applyEventToMeta records the session name + ready-for-merge lifecycle signals (#326)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.sessionName, undefined)
-  assert.equal(base.readyForMerge, undefined)
-  const named = applyEventToMeta(base, { kind: 'session-name', name: 'add-comments' }, AT)
+  assert.equal(BASE.sessionName, undefined)
+  assert.equal(BASE.readyForMerge, undefined)
+  const named = applyEventToMeta(BASE, { kind: 'session-name', name: 'add-comments' }, AT)
   assert.equal(named.sessionName, 'add-comments')
   const ready = applyEventToMeta(named, { kind: 'ready-for-merge' }, AT)
   assert.equal(ready.readyForMerge, true)
   assert.equal(ready.sessionName, 'add-comments') // ready doesn't clobber the name
 })
 
 test('applyEventToMeta records the ticket a run is implementing (#1117)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.ticket, undefined, 'a run nobody linked to a ticket says nothing')
-  const on = applyEventToMeta(base, { kind: 'ticket', path: 'tickets/2026-07-25_login.md' }, AT)
+  assert.equal(BASE.ticket, undefined, 'a run nobody linked to a ticket says nothing')
+  const on = applyEventToMeta(BASE, { kind: 'ticket', path: 'tickets/2026-07-25_login.md' }, AT)
   assert.equal(on.ticket, 'tickets/2026-07-25_login.md')
   // It is a fact about why the agent exists, so it outlives the work: a reader looking at a finished
   // run still gets to see which ticket it was.
@@ -273,9 +265,8 @@ test('applyEventToMeta records the ticket a run is implementing (#1117)', () =>
 })
 
 test('applyEventToMeta tracks the pending choice gate a run is parked on (#636)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.pendingChoice, undefined)
-  const asked = applyEventToMeta(base, { kind: 'choice', id: 'g1', title: 'Cache the auth store?', options: [{ id: 'y', label: 'Yes' }] }, AT)
+  assert.equal(BASE.pendingChoice, undefined)
+  const asked = applyEventToMeta(BASE, { kind: 'choice', id: 'g1', title: 'Cache the auth store?', options: [{ id: 'y', label: 'Yes' }] }, AT)
   assert.deepEqual(asked.pendingChoice, { id: 'g1', title: 'Cache the auth store?' })
   // A resolve for a different gate id leaves it parked; the matching resolve clears it.
   const other = applyEventToMeta(asked, { kind: 'choice-resolved', id: 'other', picked: 'y', by: 'user' }, AT)
@@ -285,8 +276,7 @@ test('applyEventToMeta tracks the pending choice gate a run is parked on (#636)'
 })
 
 test('applyEventToMeta clears a pending choice when the run ends (#636)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  const asked = applyEventToMeta(base, { kind: 'choice', id: 'g1', title: 'q?', options: [{ id: 'y', label: 'Yes' }] }, AT)
+  const asked = applyEventToMeta(BASE, { kind: 'choice', id: 'g1', title: 'q?', options: [{ id: 'y', label: 'Yes' }] }, AT)
   const ended = applyEventToMeta(asked, { kind: 'end', ok: true }, AT)
   assert.equal(ended.pendingChoice, undefined)
 })
@@ -891,17 +881,15 @@ test('startedAtFromAgentId inverts agentIdFromStartedAt, and refuses foreign ids
 test('applyEventToMeta records the pull request a session opened (E6)', () => {
   // The number is a fact about the agent, so the agent writes it down — rather than every later
   // surface re-deriving it from branch names and creation times.
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  assert.equal(base.pr, undefined, 'a session with no PR says nothing')
-  const on = applyEventToMeta(base, { kind: 'pull-request', number: 42, url: 'https://x/pull/42' }, AT)
+  assert.equal(BASE.pr, undefined, 'a session with no PR says nothing')
+  const on = applyEventToMeta(BASE, { kind: 'pull-request', number: 42, url: 'https://x/pull/42' }, AT)
   assert.deepEqual(on.pr, { number: 42, url: 'https://x/pull/42' })
   // It must outlive the agent: every read of it happens after the session has ended.
   assert.deepEqual(applyEventToMeta(on, { kind: 'end', ok: true }, AT).pr, { number: 42, url: 'https://x/pull/42' })
 })
 
 test('applyEventToMeta records the branch a branch event names (#1277)', () => {
-  const base = metaFromEvents(RUN.slice(0, 3), AT)
-  const on = applyEventToMeta(base, { kind: 'branch', branch: 'tf-agent-r1' }, AT)
+  const on = applyEventToMeta(BASE, { kind: 'branch', branch: 'tf-agent-r1' }, AT)
   assert.equal(on.branch, 'tf-agent-r1')
   // A rename mid-run replaces it: the meta always names the branch the work is on now.
   const renamed = applyEventToMeta(on, { kind: 'branch', branch: 'tf-cool-name' }, AT)

packages/framework/src/store/agent-store.ts

@@ -541,13 +541,6 @@ async function stopAndArchiveLive(fs: StoreFs, dir: string, meta: AgentMeta): Pr
   return stopped
 }
 
-/** Rebuild {@link AgentMeta} from a full event log (used when resuming). */
-export function metaFromEvents(events: readonly FrameworkEvent[], startedAt: string): AgentMeta {
-  let meta = freshMeta(startedAt)
-  for (const event of events) meta = applyEventToMeta(meta, event, startedAt)
-  return meta
-}
-
 /**
  * Durable, append-only store for a single agent's orchestration events, plus a
  * derived {@link AgentMeta} snapshot. Writes are serialized through one tail

packages/framework/src/store/index.ts

@@ -2,7 +2,6 @@ export {
   AgentStore,
   nodeStoreFs,
   applyEventToMeta,
-  metaFromEvents,
   listAgents,
   readAllAgents as readAllAgents,
   findAgent,