zooid 0.14.1 → 0.16.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AcpRuntime, ApprovalCorrelator, TapEvent, ZooidConfig, AcpAgentRegistry } from '@zooid/core';
+import { AcpRuntime, ApprovalCorrelator, TapEvent, SessionLifecycleEvent, ZooidConfig, AcpAgentRegistry } from '@zooid/core';
 import { SpawnRegistry } from '@zooid/context-mcp';
 
 interface BuildAcpRegistryOptions {
@@ -8,6 +8,7 @@ interface BuildAcpRegistryOptions {
     approvals?: ApprovalCorrelator;
     /** Observability tap forwarded to each AcpClient. */
     onTap?: (agentName: string, event: TapEvent) => void;
+    onLifecycle?: (agentName: string, event: SessionLifecycleEvent) => void;
     /**
      * Per-agent state root (`<dataRoot>/agents/`). When set, each AcpClient
      * persists its `(threadId → sessionId)` map under

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   buildAcpRegistry
-} from "./chunk-R5S26T7B.js";
+} from "./chunk-HE7DVDJA.js";
 export {
   buildAcpRegistry
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zooid",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "An open-source, self-hostable chat app for collaborating with AI agents alongside your team. Any model, any CLI.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "zooid": {
-    "webVersion": "0.12.0"
+    "webVersion": "0.12.1"
   },
   "engines": {
     "node": ">=22"
@@ -43,14 +43,14 @@
     "tar": "^7.5.16",
     "web-push": "^3.6.7",
     "yaml": "^2.5.0",
-    "@zooid/context-mcp": "^0.14.1",
-    "@zooid/acp-client": "^0.14.1",
-    "@zooid/transport-matrix": "^0.14.1",
-    "@zooid/runtime-docker": "^0.14.1",
-    "@zooid/core": "^0.14.1",
-    "@zooid/runtime-local": "^0.14.1",
-    "@zooid/transport-http": "^0.14.1",
-    "@zooid/pi-extension": "^0.13.1"
+    "@zooid/acp-client": "^0.16.0",
+    "@zooid/context-mcp": "^0.16.0",
+    "@zooid/core": "^0.16.0",
+    "@zooid/runtime-docker": "^0.16.0",
+    "@zooid/pi-extension": "^0.13.3",
+    "@zooid/transport-http": "^0.16.0",
+    "@zooid/transport-matrix": "^0.16.0",
+    "@zooid/runtime-local": "^0.16.0"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "^0.21.0",

package/src/build-registry.context.test.ts

@@ -28,6 +28,7 @@ const matrixCfg: ZooidConfig = {
       hooks: {},
       acp: { command: 'fake', args: [] },
       approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
       matrix: {
         transport: 'mx',
         user_id: '@architect:hs',

package/src/build-registry.test.ts

@@ -15,6 +15,7 @@ function cfg(overrides: Partial<ZooidConfig> & Pick<ZooidConfig, 'runtime'>): Zo
         hooks: {},
         acp: { preset: 'claude' },
         approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
         http: { transport: 'http-local' },
       },
     },

package/src/build-registry.ts

@@ -10,6 +10,7 @@ import {
   type ContextSpawnFactory,
   type MountConfig,
   type TapEvent,
+  type SessionLifecycleEvent,
   type ZooidConfig,
   type TransportContextProvider,
 } from '@zooid/core'
@@ -29,6 +30,7 @@ export interface BuildAcpRegistryOptions {
   approvals?: ApprovalCorrelator
   /** Observability tap forwarded to each AcpClient. */
   onTap?: (agentName: string, event: TapEvent) => void
+  onLifecycle?: (agentName: string, event: SessionLifecycleEvent) => void
   /**
    * Per-agent state root (`<dataRoot>/agents/`). When set, each AcpClient
    * persists its `(threadId → sessionId)` map under
@@ -314,6 +316,7 @@ export function buildAcpRegistry(
     cwd: cwdByAgent,
     approvals: opts.approvals,
     onTap: opts.onTap,
+    onLifecycle: opts.onLifecycle,
     agentsDir: opts.agentsDir,
     contextSpawns,
     onSessionEstablished: (agentName, sessionKey, sessionId) =>

package/src/build-registry.zod043.test.ts

@@ -25,6 +25,7 @@ function makeCfg(over: Partial<ZooidConfig> = {}): ZooidConfig {
         hooks: {},
         acp: { preset: 'claude' },
         approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
         matrix: {
           transport: 'm1',
           user_id: '@alice:localhost',

package/src/build-registry.zod044.test.ts

@@ -24,6 +24,7 @@ function mkCfg(over: Partial<ZooidConfig['agents']['alice']> = {}): ZooidConfig
         hooks: {},
         acp: { preset: 'claude' },
         approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
         matrix: {
           transport: 'm1',
           user_id: '@alice:localhost',

package/src/commands/dev.ts

@@ -208,6 +208,7 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
             // the web client without needing an invite.
             publicWorkforceSpace: true,
             onTap: (agentName, event) => captures[agentName]?.onTap(event),
+            onLifecycle: (agentName, event) => captures[agentName]?.onLifecycle(event),
             prepullLog: (line) => {
               t.output = line.replace(/^\[zooid\]\s+/, '').trim()
             },
@@ -251,6 +252,8 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
           const app = webStatic({
             webRoot,
             homeserverUrl: homeserver,
+            // Same default as the daemon's space provisioning (start-daemon.ts).
+            workforceSpace: matrix.transport.space ?? 'dev',
             ...(ctx.daemon?.vapidPublicKey
               ? {
                   // Tuwunel runs in a container; `localhost` here would

package/src/commands/start.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path'
 import type { CliFlags } from '@zooid/core'
 import { resolveDataLayout } from '../bootstrap/data-layout.js'
 import { startDaemon } from '../daemon/start-daemon.js'
+import { logLifecycle } from '../observability/lifecycle-log.js'
 
 export interface StartFlags extends CliFlags {
   printToken?: boolean
@@ -21,6 +22,7 @@ export async function runStart(flags: StartFlags): Promise<void> {
     cliFlags: flags,
     installSignalHandlers: true,
     agentsDir: layout.agentsDir,
+    onLifecycle: (agentName, event) => logLifecycle(agentName, event),
   })
   console.log(`zooid listening on http://localhost:${handle.port}`)
   for (const name of handle.agentNames) console.log(`  agent: ${name}`)

package/src/daemon/start-daemon.ts

@@ -13,6 +13,7 @@ import {
   mergeCliFlags,
   type CliFlags,
   type TapEvent,
+  type SessionLifecycleEvent,
 } from '@zooid/core'
 import { createApp } from '@zooid/transport-http'
 import {
@@ -49,6 +50,7 @@ export interface StartDaemonOpts {
   adminUserId?: string
   /** Observability tap forwarded to each AcpClient. */
   onTap?: (agentName: string, event: TapEvent) => void
+  onLifecycle?: (agentName: string, event: SessionLifecycleEvent) => void
   /**
    * Per-agent state root (`<dataRoot>/agents/`). Threaded into
    * `buildAcpRegistry` so each AcpClient persists `sessionId`s across
@@ -137,6 +139,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
   const registry = buildAcpRegistry(config, {
     approvals,
     onTap: opts.onTap,
+    onLifecycle: opts.onLifecycle,
     agentsDir: opts.agentsDir,
     contextSpawnRegistry,
     daemonSockPaths: contextSockets.paths,
@@ -322,6 +325,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
           resolveRoom,
           ensureBot,
           sendMessage: (m) => client.sendMessage(m),
+          getJoinedMembers: (roomId, asUserId) => client.getJoinedMembers(roomId, asUserId),
         })
         for (const [name] of webhookTriggers) {
           console.log(`[webhook] POST ${WEBHOOK_ROUTE_PREFIX}/${name}`)
@@ -383,6 +387,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
         resolveRoom,
         ensureBot,
         sendMessage: (m) => client.sendMessage(m),
+        getJoinedMembers: (roomId, asUserId) => client.getJoinedMembers(roomId, asUserId),
       })
       const scheduled = Object.values(config.triggers).filter((t) => t.schedule).length
       if (scheduled > 0) console.log(`[trigger] scheduled ${scheduled} trigger(s)`)
@@ -424,6 +429,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
           spaceRoomId,
           asUserId,
           getAgents: () => bindings,
+          stateKey: matrix.transport.workstation ?? '',
         })
         console.log(`[matrix] published dev.zooid.workforce (${bindings.length} agents)`)
         void publisher

package/src/daemon/trigger-runner.mxid.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireTrigger } from './trigger-runner.js'
+
+const deps = (mention: string, agentUserIds: Record<string, string>) => {
+  const sendMessage = vi.fn(async () => ({ event_id: '$1' }))
+  return {
+    sendMessage,
+    call: () =>
+      fireTrigger({
+        name: 'standup',
+        as: '@cloud.cron:zooid.zoon.eco',
+        message: { room: '#product:zooid.zoon.eco', mention, text: 'Morning standup.' },
+        agentUserIds,
+        resolveRoom: async () => '!room:zooid.zoon.eco',
+        ensureBot: async () => {},
+        sendMessage,
+      }),
+  }
+}
+
+describe('fireTrigger addressing', () => {
+  it('uses an MXID mention verbatim, with no local lookup', async () => {
+    const { call, sendMessage } = deps('@ori-macbook.cpo:zooid.zoon.eco', {})
+    await call()
+    expect(sendMessage.mock.calls[0]![0].content['m.mentions']).toEqual({
+      user_ids: ['@ori-macbook.cpo:zooid.zoon.eco'],
+    })
+  })
+
+  it('resolves a bare name through the local agent map', async () => {
+    const { call, sendMessage } = deps('scout', { scout: '@cloud.scout:zooid.zoon.eco' })
+    await call()
+    expect(sendMessage.mock.calls[0]![0].content['m.mentions']).toEqual({
+      user_ids: ['@cloud.scout:zooid.zoon.eco'],
+    })
+  })
+
+  it('stamps dev.zooid.trigger with the trigger name and firing time', async () => {
+    const { call, sendMessage } = deps('@ori-macbook.cpo:zooid.zoon.eco', {})
+    const before = Date.now()
+    await call()
+    const stamp = sendMessage.mock.calls[0]![0].content['dev.zooid.trigger'] as {
+      name: string
+      fired_at: number
+      ttl_ms?: number
+    }
+    expect(stamp.name).toBe('standup')
+    expect(stamp.fired_at).toBeGreaterThanOrEqual(before)
+  })
+
+  it('skips a bare name with no local binding rather than posting', async () => {
+    const { call, sendMessage } = deps('scout', {})
+    await call()
+    expect(sendMessage).not.toHaveBeenCalled()
+  })
+})
+
+describe('fireTrigger mention rendering', () => {
+  it('leads the body with the MXID so the room can see who was addressed', async () => {
+    const { call, sendMessage } = deps('@ori-macbook.cpo:zooid.zoon.eco', {})
+    await call()
+    expect(sendMessage.mock.calls[0]![0].content.body).toBe(
+      '@ori-macbook.cpo:zooid.zoon.eco Morning standup.',
+    )
+  })
+
+  it('sends no HTML — the client pills a bare MXID, and markup would need escaping', async () => {
+    const { call, sendMessage } = deps('@ori-macbook.cpo:zooid.zoon.eco', {})
+    await call()
+    const c = sendMessage.mock.calls[0]![0].content
+    expect(c.format).toBeUndefined()
+    expect(c.formatted_body).toBeUndefined()
+  })
+
+  it('warns when the addressed user is not in the room', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const sendMessage = vi.fn(async () => ({ event_id: '$1' }))
+    await fireTrigger({
+      name: 'standup',
+      as: '@cloud.cron:zooid.zoon.eco',
+      message: {
+        room: '#product:zooid.zoon.eco',
+        mention: '@ori-macbook.cpo:zooid.zoon.eco',
+        text: 'Morning standup.',
+      },
+      agentUserIds: {},
+      resolveRoom: async () => '!p:zooid.zoon.eco',
+      ensureBot: async () => {},
+      sendMessage,
+      getJoinedMembers: async () => ({ joined: { '@cloud.product:zooid.zoon.eco': {} } }),
+    })
+    // posted anyway — the agent may join before it expires
+    expect(sendMessage).toHaveBeenCalledTimes(1)
+    expect(warn).toHaveBeenCalledWith(expect.stringMatching(/not in .*#product/))
+    warn.mockRestore()
+  })
+
+  it('warns only once across repeated fires at the same absent target', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const getJoinedMembers = vi.fn(async () => ({ joined: {} }))
+    // A distinct trigger name from the previous test: `warnedTargets` is
+    // module-level (dedup lasts the daemon's process lifetime, per spec), so
+    // reusing "standup" here would find the key already warned and this
+    // test's own two calls would produce zero fresh warnings.
+    const fire = () =>
+      fireTrigger({
+        name: 'standup-repeat',
+        as: '@cloud.cron:zooid.zoon.eco',
+        message: {
+          room: '#product:zooid.zoon.eco',
+          mention: '@ori-macbook.cpo:zooid.zoon.eco',
+          text: 'Morning standup.',
+        },
+        agentUserIds: {},
+        resolveRoom: async () => '!p:zooid.zoon.eco',
+        ensureBot: async () => {},
+        sendMessage: async () => ({ event_id: '$1' }),
+        getJoinedMembers,
+      })
+    await fire()
+    await fire()
+    expect(warn).toHaveBeenCalledTimes(1)
+    warn.mockRestore()
+  })
+
+  it('leaves interpolated webhook text verbatim in the body', async () => {
+    const sendMessage = vi.fn(async () => ({ event_id: '$1' }))
+    await fireTrigger({
+      name: 'triage',
+      as: '@cloud.hook:zooid.zoon.eco',
+      message: {
+        room: '#product:zooid.zoon.eco',
+        mention: '@cloud.product:zooid.zoon.eco',
+        text: 'Triage "<img src=x> & more".',
+      },
+      agentUserIds: {},
+      resolveRoom: async () => '!r:zooid.zoon.eco',
+      ensureBot: async () => {},
+      sendMessage,
+    })
+    const c = sendMessage.mock.calls[0]![0].content
+    expect(c.body).toBe('@cloud.product:zooid.zoon.eco Triage "<img src=x> & more".')
+    expect(c.formatted_body).toBeUndefined()
+  })
+})

package/src/daemon/trigger-runner.test.ts

@@ -12,7 +12,7 @@ const deps = (over: Record<string, unknown> = {}) => ({
   name: 'image-currency',
   as: '@cron:example.org',
   message,
-  agentUserId: '@architect:example.org',
+  agentUserIds: { architect: '@architect:example.org' },
   resolveRoom: vi.fn(async () => '!room:example.org'),
   ensureBot: vi.fn(async () => {}),
   sendMessage: vi.fn(async () => ({ event_id: '$1' })),
@@ -20,14 +20,14 @@ const deps = (over: Record<string, unknown> = {}) => ({
 })
 
 describe('fireTrigger', () => {
-  it('posts text verbatim as the trigger bot user', async () => {
+  it('posts text as the trigger bot user, led by a visible mention', async () => {
     const d = deps()
     await fireTrigger(d as never)
     expect(d.sendMessage).toHaveBeenCalledTimes(1)
     const call = (d.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]
     expect(call.roomId).toBe('!room:example.org')
     expect(call.asUserId).toBe('@cron:example.org')
-    expect(call.content.body).toBe('Check the pinned agent CLI versions.')
+    expect(call.content.body).toBe('@architect:example.org Check the pinned agent CLI versions.')
     expect(call.content.msgtype).toBe('m.text')
   })
 
@@ -36,7 +36,6 @@ describe('fireTrigger', () => {
     await fireTrigger(d as never)
     const content = (d.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content
     expect(content['m.mentions']).toEqual({ user_ids: ['@architect:example.org'] })
-    expect(content.body).not.toContain('@architect')
   })
 
   it('posts at the top level, never into a thread — runTurn makes each firing a new root', async () => {

package/src/daemon/trigger-runner.ts

@@ -1,10 +1,12 @@
 import type { TriggerMessage } from '@zooid/core'
+import { buildMentionContent } from '@zooid/transport-matrix'
 
 export interface FireTriggerDeps {
   name: string
   as: string
   message: TriggerMessage
-  agentUserId: string
+  /** Local agent name → MXID. A `mention:` that is already an MXID bypasses this. */
+  agentUserIds: Record<string, string>
   resolveRoom: (room: string) => Promise<string | null>
   ensureBot: (asUserId: string, roomId: string) => Promise<void>
   sendMessage: (input: {
@@ -12,11 +14,29 @@ export interface FireTriggerDeps {
     asUserId: string
     content: { msgtype: string; body: string; [k: string]: unknown }
   }) => Promise<{ event_id: string }>
+  /**
+   * Optional: enables the [[ZOD081]] §Design 6 "nobody is listening" warning.
+   * Omitted in tests that don't care about it — the check is then skipped
+   * silently, never a hard requirement to fire.
+   */
+  getJoinedMembers?: (roomId: string, asUserId: string) => Promise<{ joined: Record<string, unknown> }>
 }
 
+// Module-level so a daily trigger against an off laptop logs once per daemon
+// run, not once a day. Keyed by trigger name + target so distinct triggers
+// (or targets) each get their own first warning.
+const warnedTargets = new Set<string>()
+
 export async function fireTrigger(deps: FireTriggerDeps): Promise<void> {
-  const { name, as, message, agentUserId, resolveRoom, ensureBot, sendMessage } = deps
+  const { name, as, message, agentUserIds, resolveRoom, ensureBot, sendMessage, getJoinedMembers } = deps
   try {
+    const target = message.mention.startsWith('@')
+      ? message.mention
+      : agentUserIds[message.mention]
+    if (!target) {
+      console.warn(`[trigger:${name}] unknown agent "${message.mention}" — skipping`)
+      return
+    }
     const roomId = await resolveRoom(message.room)
     if (!roomId) {
       console.warn(`[trigger:${name}] cannot resolve room ${message.room} — skipping`)
@@ -27,13 +47,31 @@ export async function fireTrigger(deps: FireTriggerDeps): Promise<void> {
       roomId,
       asUserId: as,
       content: {
-        msgtype: 'm.text',
-        body: message.text,
-        // Structural mention: routes deterministically AND disarms the raw-body
-        // fallback in extractMentions, which only fires when nothing matched.
-        'm.mentions': { user_ids: [agentUserId] },
+        ...buildMentionContent({ userId: target, text: message.text, msgtype: 'm.text' }),
+        'dev.zooid.trigger': {
+          name,
+          fired_at: Date.now(),
+          ...(message.ttlMs !== undefined ? { ttl_ms: message.ttlMs } : {}),
+        },
       },
     })
+
+    // Post first, warn second: an absent target isn't a lost message —
+    // catch-up may still deliver it if that agent joins before it expires.
+    // Membership, not registration: router.ts routes only to agents joined
+    // to the room, so an agent that exists but isn't in the room misses the
+    // firing exactly as an unregistered one does.
+    if (getJoinedMembers) {
+      const { joined } = await getJoinedMembers(roomId, as)
+      const key = `${name}|${target}`
+      if (!(target in joined) && !warnedTargets.has(key)) {
+        warnedTargets.add(key)
+        console.warn(
+          `[trigger:${name}] ${target} is not in ${message.room} — nothing will handle this ` +
+            `unless that agent joins before the message expires`,
+        )
+      }
+    }
   } catch (err) {
     // Never throw: one bad firing must not take down the scheduler.
     console.warn(`[trigger:${name}] failed:`, (err as Error).message)

package/src/daemon/trigger-scheduler.ts

@@ -8,6 +8,7 @@ export interface StartTriggerSchedulerDeps {
   resolveRoom: FireTriggerDeps['resolveRoom']
   ensureBot: FireTriggerDeps['ensureBot']
   sendMessage: FireTriggerDeps['sendMessage']
+  getJoinedMembers?: FireTriggerDeps['getJoinedMembers']
 }
 
 export interface TriggerSchedulerHandle {
@@ -29,19 +30,23 @@ export function validateCron(name: string, expr: string): void {
 }
 
 export function startTriggerScheduler(deps: StartTriggerSchedulerDeps): TriggerSchedulerHandle {
-  const { triggers, agentUserIds, resolveRoom, ensureBot, sendMessage } = deps
+  const { triggers, agentUserIds, resolveRoom, ensureBot, sendMessage, getJoinedMembers } = deps
   const jobs: Cron[] = []
 
   for (const [name, trigger] of Object.entries(triggers)) {
     if (!trigger.schedule) continue
     const job = new Cron(trigger.schedule, () => {
       for (const message of trigger.messages) {
-        const agentUserId = agentUserIds[message.mention]
-        if (!agentUserId) {
-          console.warn(`[trigger:${name}] unknown agent "${message.mention}" — skipping`)
-          continue
-        }
-        void fireTrigger({ name, as: trigger.as, message, agentUserId, resolveRoom, ensureBot, sendMessage })
+        void fireTrigger({
+          name,
+          as: trigger.as,
+          message,
+          agentUserIds,
+          resolveRoom,
+          ensureBot,
+          sendMessage,
+          getJoinedMembers,
+        })
       }
     })
     jobs.push(job)

package/src/daemon/webhook-routes.ts

@@ -84,6 +84,7 @@ export interface WebhookDeps {
   resolveRoom: FireTriggerDeps['resolveRoom']
   ensureBot: FireTriggerDeps['ensureBot']
   sendMessage: FireTriggerDeps['sendMessage']
+  getJoinedMembers?: FireTriggerDeps['getJoinedMembers']
 }
 
 /**
@@ -166,20 +167,15 @@ async function handleDelivery(
     for (const message of trigger.messages) {
       if (message.match !== undefined && !evaluateMatch(message.match, ctx)) continue
 
-      const agentUserId = deps.agentUserIds[message.mention]
-      if (!agentUserId) {
-        console.warn(`[webhook:${name}] unknown agent "${message.mention}" — skipping`)
-        continue
-      }
-
       await fireTrigger({
         name,
         as: trigger.as,
         message: { ...message, text: renderTemplate(message.text, ctx) },
-        agentUserId,
+        agentUserIds: deps.agentUserIds,
         resolveRoom: deps.resolveRoom,
         ensureBot: deps.ensureBot,
         sendMessage: deps.sendMessage,
+        getJoinedMembers: deps.getJoinedMembers,
       })
     }
   } catch (err) {

package/src/observability/capture-agent.ts

@@ -1,4 +1,4 @@
-import type { TapEvent } from '@zooid/core'
+import type { TapEvent, SessionLifecycleEvent } from '@zooid/core'
 import type { LogPaths } from './paths.js'
 import { JsonlSink, shouldCaptureUpdate, type Verbosity } from './file-sink.js'
 
@@ -19,13 +19,28 @@ export interface WireAgentCaptureOpts {
 
 export interface AgentCapture {
   onTap: (event: TapEvent) => void
+  onLifecycle: (event: SessionLifecycleEvent) => void
+  readLifecycleCounters: () => LifecycleCounters
   close: () => Promise<void>
 }
 
+export interface LifecycleCounters {
+  closeAttempts: number
+  closeSuccesses: number
+  sessionsReclaimed: number
+  recoveries: Record<'cached' | 'resume' | 'load' | 'new', number>
+}
+
 export function wireAgentCapture(opts: WireAgentCaptureOpts): AgentCapture {
   const sink = new JsonlSink(opts.paths.agentTap(opts.agent))
   const now = opts.now ?? (() => new Date())
   const pending: Promise<unknown>[] = []
+  const counters: LifecycleCounters = {
+    closeAttempts: 0,
+    closeSuccesses: 0,
+    sessionsReclaimed: 0,
+    recoveries: { cached: 0, resume: 0, load: 0, new: 0 },
+  }
 
   const onTap = (event: TapEvent): void => {
     if (event.kind === 'session_update') {
@@ -50,6 +65,25 @@ export function wireAgentCapture(opts: WireAgentCaptureOpts): AgentCapture {
 
   return {
     onTap,
+    onLifecycle: (event) => {
+      if (event.reason && event.outcome !== 'unsupported') counters.closeAttempts++
+      if (event.reason && event.outcome === 'closed') {
+        counters.closeSuccesses++
+        counters.sessionsReclaimed++
+      }
+      if (event.outcome === 'recovered' && event.recoveryMethod) counters.recoveries[event.recoveryMethod]++
+      pending.push(sink.write({
+        ts: now().toISOString(),
+        agent: opts.agent,
+        kind: 'session_lifecycle',
+        session_key: event.sessionKey,
+        session_id: event.sessionId,
+        reason: event.reason,
+        outcome: event.outcome,
+        recovery_method: event.recoveryMethod,
+      }))
+    },
+    readLifecycleCounters: () => ({ ...counters, recoveries: { ...counters.recoveries } }),
     close: async () => {
       await Promise.all(pending)
       await sink.close()

package/src/observability/lifecycle-log.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionLifecycleEvent } from '@zooid/core'
+import { formatLifecycleLine, logLifecycle } from './lifecycle-log.js'
+
+const base = { agentId: 'architect', sessionKey: '$root', sessionId: 's-1' }
+
+function sink() {
+  return { log: vi.fn(), error: vi.fn() }
+}
+
+describe('lifecycle log', () => {
+  it('formats closes with reason and outcome', () => {
+    expect(formatLifecycleLine('architect', { ...base, reason: 'idle', outcome: 'closed' })).toBe(
+      '[lifecycle] architect key=$root session=s-1 idle → closed',
+    )
+    expect(formatLifecycleLine('architect', { ...base, reason: 'clear', outcome: 'closed' })).toBe(
+      '[lifecycle] architect key=$root session=s-1 clear → closed',
+    )
+  })
+
+  it('formats recoveries with their method', () => {
+    expect(
+      formatLifecycleLine('architect', { ...base, outcome: 'recovered', recoveryMethod: 'resume' }),
+    ).toBe('[lifecycle] architect key=$root session=s-1 recovered (resume)')
+  })
+
+  it('skips cached hits, which fire on every prompt to a live session', () => {
+    expect(
+      formatLifecycleLine('architect', { ...base, outcome: 'recovered', recoveryMethod: 'cached' }),
+    ).toBeNull()
+  })
+
+  it('routes failed closes to stderr and the rest to stdout', () => {
+    const out = sink()
+    logLifecycle('architect', { ...base, reason: 'idle', outcome: 'failed' }, out)
+    logLifecycle('architect', { ...base, reason: 'idle', outcome: 'closed' }, out)
+    expect(out.error).toHaveBeenCalledWith('[lifecycle] architect key=$root session=s-1 idle → failed')
+    expect(out.log).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips unsupported, which the ACP client already warns about', () => {
+    const out = sink()
+    const event: SessionLifecycleEvent = { ...base, reason: 'idle', outcome: 'unsupported' }
+    logLifecycle('architect', event, out)
+    expect(out.log).not.toHaveBeenCalled()
+    expect(out.error).not.toHaveBeenCalled()
+  })
+})