fix(agent-gateway): seed agent phase when a transcript attaches mid-turn (#365)

## Requirement or Bug

Resolve #350

## Bug Reproduction Steps

In `transcriptContract.e2e.test.ts` S3, add `await new Promise((r) =>
setTimeout(r, 3000));` after `submitPrompt`. It then fails every time
with `expect(mid.meta.agent).toBeDefined()`. Without the sleep it fails
about 1 run in 4, and more often under load.

## Root Cause

The transcript store binds to the event bus lazily, on the first
transcript request. `meta.agent.phase` comes only from the projector's
phase merge, and that merge runs only when a new bus event arrives. On a
late attach, `subscribeAgent` (`coreBinding.ts`) restores the running
turn with `seedActiveTurn`, but it does not restore the phase.
`seedPendingInteractions` then adds the approval. The turn is blocked on
that approval, so no further event comes and `meta.agent` stays
undefined. In the product, a client that opens or reloads a session
while an approval is pending shows the approval with no agent status.
Fundamental fix.

## Code Changes

- `coreEventMap.ts`: new `AgentTranscriptProjector.seedPhase()`. It
recomputes the phase from the activity snapshot and the pending
approvals, and returns one `meta.merge`. The tracker set-up moves to
`tracker()`, which `phaseFor` reuses.
- `coreBinding.ts`: when attaching to a turn that is already running,
apply `seedPhase()` after `seedActiveTurn`. Idle and new agents are not
touched. A later phase event with the same value is deduplicated by the
tracker's `lastPhaseKey`.
- Test: `transcript.test.ts` checks that `seedPhase()` gives
`awaiting_approval` for a turn blocked on an approval.

Not in scope: `meta.agent.model` and `meta.agent.permission` on late
attach. S3 needs only the phase.

## Behavior Changes and Affected Users

| Behavior | Before | After | Who relies on the old behavior | Escape
hatch |
| --- | --- | --- | --- | --- |
| Transcript first opened while a turn is running | `meta.agent` missing
until the next phase event (never, if the turn is blocked on an
approval) | `meta.agent.phase` is set immediately | None. Clients
already handle `meta.agent.phase` from live events | None needed |

Consumers: web, desktop, and inspector clients that read
`meta.agent.phase`. The wire shape is unchanged. Verification:
forced-late S3 fails 2/2 without the fix and passes 2/2 with it. Full
agent-gateway suite: 1408/1408.

No quarantine for S3 exists in the repo, so there is nothing to remove.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [x] I have linked a related issue (external PRs: issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] The behavior-change table above is complete, and every removed
behavior or flipped default is named in the changeset and either has an
escape hatch or was explicitly approved by a maintainer in this PR.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.

Author: elkaix

.changeset/transcript-phase-on-attach.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": patch
+---
+
+Clients that open a session while a tool approval is pending now show the agent's status instead of none.

packages/agent-gateway/src/services/transcript/coreBinding.ts

@@ -155,6 +155,7 @@ export function bindSessionTranscript(
     if (loopStatus?.state === 'running' && loopStatus.activeTurnId !== undefined) {
       const promptId = loopStatus.activePromptId;
       projector.seedActiveTurn({ turnId: loopStatus.activeTurnId, promptId });
+      applyOps(handle.id, projector.seedPhase());
     }
     const list = agentDisposables.get(handle.id) ?? [];
     list.push(busD);

packages/agent-gateway/src/services/transcript/coreEventMap.ts

@@ -357,15 +357,25 @@ export class AgentTranscriptProjector {
     return [...ops, { op: 'meta.merge', meta: { agent: { phase } } }];
   }
 
-  private phaseFor(event: ProjectorBusEvent): ReturnType<typeof toLegacyPhase> {
+  seedPhase(): TranscriptOperation[] {
+    const phase = this.tracker()?.recompute();
+    return phase === undefined ? [] : [{ op: 'meta.merge', meta: { agent: { phase } } }];
+  }
+
+  private tracker(): LegacyActivityTracker | undefined {
     if (this.lookups?.activitySnapshot === undefined || this.lookups.pendingApprovals === undefined) {
       return undefined;
     }
     this.activityTracker ??= new LegacyActivityTracker(
       this.lookups.activitySnapshot,
       this.lookups.pendingApprovals,
     );
-    return phaseFromDomainEvent(this.activityTracker, event);
+    return this.activityTracker;
+  }
+
+  private phaseFor(event: ProjectorBusEvent): ReturnType<typeof toLegacyPhase> {
+    const tracker = this.tracker();
+    return tracker === undefined ? undefined : phaseFromDomainEvent(tracker, event);
   }
 
   private mapEvent(event: ProjectorBusEvent): TranscriptOperation[] {

packages/agent-gateway/test/services/transcript.test.ts

@@ -1597,6 +1597,24 @@ describe('AgentTranscriptProjector', () => {
     expect(tx.getMeta().agent).toMatchObject({ model: 'k3', thinkingEffort: 'high' });
   });
 
+  it('seeds meta.agent.phase when attaching to a turn blocked on an approval', () => {
+    const projector = new AgentTranscriptProjector('main', TEST_SESSION_ID, {
+      activitySnapshot: () => ({
+        turn: { turnId: 1, phase: 'running', step: 1, ending: false, activeToolCalls: [], since: 1000 },
+      }),
+      pendingApprovals: () => [{ approvalId: 'ap1', toolCallId: 'c1', since: 1500 }],
+    });
+    const tx = new AgentTranscript('main');
+
+    tx.apply(projector.seedPhase());
+
+    expect(tx.getMeta().agent?.phase).toMatchObject({
+      kind: 'awaiting_approval',
+      turnId: 1,
+      approval: { approvalId: 'ap1', toolCallId: 'c1' },
+    });
+  });
+
   it('maps domain events into meta.agent.phase', () => {
     let snapshot: AgentActivitySnapshot = {};
     let approvals: readonly LegacyActivityApproval[] = [];