fix: surface config startup failures

packages/core/agent-loop/README.md

@@ -41,7 +41,7 @@ interface Config {
 }
 ```
 
-Agents listed in config are auto-created at startup. `cwd` seeds a fresh config-created session; a materialized exact `sessionId` remount and an explicit `resumeSessionId` keep the persisted session header. Config agents have no per-agent persona field: they use `dsh-system-prompt`'s deployment default, while programmatic factory callers can register an agent-scoped `deployment:persona` shadow in `setup`. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from `assembleContextFor(agent)` — the helper couples the typed agent with its matching scope selector. These are runtime facts of the agents THIS loop drives, unlike the `harness:identity` and default `deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
+Agents listed in config are auto-created at startup. `cwd` seeds a fresh config-created session; a materialized exact `sessionId` remount and an explicit `resumeSessionId` keep the persisted session header. A declarative lookup, resume, setup, or publication failure is contained, logged, and emitted as `agent-loop/config-start-failed(sessionId, error)` because no live `Agent` exists for an `agent/*` signal. Config agents have no per-agent persona field: they use `dsh-system-prompt`'s deployment default, while programmatic factory callers can register an agent-scoped `deployment:persona` shadow in `setup`. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from `assembleContextFor(agent)` — the helper couples the typed agent with its matching scope selector. These are runtime facts of the agents THIS loop drives, unlike the `harness:identity` and default `deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
 
 ### Exported concrete class
 

packages/core/agent-loop/src/index.ts

@@ -327,6 +327,17 @@ declare module 'cordis' {
   interface Context {
     agentLoop: AgentLoop
   }
+  interface Events {
+    /**
+     * A declarative agent entry failed before it could publish a live agent.
+     * Consumers that buffer work for the configured identity use this
+     * transient signal to reject that work instead of waiting forever.
+     * @param sessionId - exact shared agent/session identity that failed startup.
+     * @param error - persistence, setup, or publication failure.
+     * @mode emit
+     */
+    'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+  }
 }
 
 /** Plugin configuration for declarative startup agents. */
@@ -381,7 +392,7 @@ export class AgentLoop extends Service implements AgentFactory {
           this.create(configuredId, options, meta)
         } else {
           const startup = this.restoreOrCreateConfigured(ctx, persistence, configuredId, options, meta).catch((error: unknown) => {
-            ctx.logger.warn(`agent "${id}": config-driven restore of "${configuredId}" failed: ${String(error)}`)
+            this.reportConfiguredStartupFailure(id, 'restore', configuredId, error)
           })
           this.ownership.trackStartup(startup)
         }
@@ -396,7 +407,7 @@ export class AgentLoop extends Service implements AgentFactory {
             resumeSessionId,
             agentOptions: options,
           }).catch((error: unknown) => {
-            ctx.logger.warn(`agent "${id}": config-driven resume of "${resumeSessionId}" failed: ${String(error)}`)
+            this.reportConfiguredStartupFailure(id, 'resume', resumeSessionId, error)
           })
         })
         return fiber.dispose
@@ -404,6 +415,21 @@ export class AgentLoop extends Service implements AgentFactory {
     }
   }
 
+  /** Report a contained declarative-start failure to identity-bound consumers. */
+  private reportConfiguredStartupFailure(
+    configId: string,
+    action: 'restore' | 'resume',
+    sessionId: SessionId,
+    error: unknown,
+  ): void {
+    this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${String(error)}`)
+    try {
+      this.ctx.emit('agent-loop/config-start-failed', sessionId, error)
+    } catch (listenerError) {
+      this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${String(listenerError)}`)
+    }
+  }
+
   /** Restore a materialized exact config identity on remount, or create it on first use. */
   private async restoreOrCreateConfigured(
     ownerCtx: Context,

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -98,6 +98,12 @@ describe('config-driven session id', () => {
     const ctx = await makeCoreContext()
     await ctx.plugin(SessionPersistenceJsonl, { root })
     const failure = new Error('persistence index failed')
+    const listenerFailure = new Error('failure observer failed')
+    const failures: { sessionId: SessionId; error: unknown }[] = []
+    ctx.on('agent-loop/config-start-failed', (sessionId, error) => {
+      failures.push({ sessionId, error })
+    })
+    ctx.on('agent-loop/config-start-failed', () => { throw listenerFailure })
     vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(failure)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
 
@@ -108,6 +114,10 @@ describe('config-driven session id', () => {
     await expect.poll(() => warn).toHaveBeenCalledWith(expect.stringContaining(
       'config-driven restore of "stdio-exact-failure" failed: Error: persistence index failed',
     ))
+    expect(failures).toEqual([{ sessionId: SessionId('stdio-exact-failure'), error: failure }])
+    expect(warn).toHaveBeenCalledWith(
+      'agent "main": config-start-failed listener threw: Error: failure observer failed',
+    )
     expect(ctx.agents.get(SessionId('stdio-exact-failure'))).toBeUndefined()
     warn.mockRestore()
     await ctx.fiber.dispose()