fix(framework): make the GitHub Actions run target actually run end to end (#1050) (#1082)

* fix(framework): grant id-token: write so the agent workflow can authenticate

anthropics/claude-code-action@v1 exchanges an OIDC token to authenticate the
subscription OAuth token (claude_code_oauth_token). Without id-token: write in
the workflow permissions every run fails with "Could not fetch an OIDC token.
Did you remember to add id-token: write to your workflow permissions?", so the
agent step never runs.

Refs #1050

* fix(framework): make the Actions run correlation id unique per process

The correlation id seeded a module-level session counter, so a fresh
`framework run` process (the daemon spawns one per run) restarted it at 1 and
every run's first turn was `actions-1-turn-1`. A new run could then match an
earlier, identically named run still in the recent-runs window and return its
stale conclusion. Mix a random tag into the session id so a run only ever finds
its own workflow run.

Refs #1050

Author: suleimansh

.changeset/actions-unique-correlation-id.md

@@ -0,0 +1,5 @@
+---
+"@gemstack/framework": patch
+---
+
+Give each GitHub Actions run (`--run-on actions`, #1050) a correlation id that is unique across driver processes. The id seeded a per-process counter, so a fresh `framework run` process restarted it at 1 and every run's first turn was `actions-1-turn-1`; a new run could then match an earlier, identically named run still in the recent-runs window and report its stale result. The session id now mixes in a random tag, so a run only ever finds its own workflow run.

.github/workflows/framework-agent.yml

@@ -22,10 +22,13 @@ on:
         description: A prior agent session id to continue instead of starting fresh.
         required: false
 
-# The agent pushes a branch and may open a PR; nothing here needs write access to anything else.
+# The agent pushes a branch and may open a PR. `id-token: write` is not optional: the
+# action exchanges an OIDC token to authenticate the subscription OAuth token, and without
+# it every run fails with "Could not fetch an OIDC token".
 permissions:
   contents: write
   pull-requests: write
+  id-token: write
 
 jobs:
   agent:

packages/framework/src/driver/actions.test.ts

@@ -163,6 +163,14 @@ test('ActionsDriver dispatches the prompt with a correlation id and the framing
   assert.equal(body.inputs['correlation_id'], `${session.id}-turn-1`)
 })
 
+test('ActionsDriver gives each session a unique correlation prefix so a fresh process never matches a stale run (#1050)', async () => {
+  // The daemon spawns a fresh process per run, restarting the session counter, so without a
+  // random tag two runs would both be `actions-1-...` and one could latch onto the other's run.
+  const a = await makeDriver().driver.start({ cwd: '/ws' })
+  const b = await makeDriver().driver.start({ cwd: '/ws' })
+  assert.notEqual(a.id, b.id)
+})
+
 test('ActionsDriver runs the next turn on the branch the last one pushed (#610)', async () => {
   const { driver, calls } = makeDriver()
   const session = await driver.start({ cwd: '/ws' })

packages/framework/src/driver/actions.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import { StreamJsonParser } from './claude-code.js'
 import { readZip } from './actions-zip.js'
 import { combineFraming, makeEmit } from './session-support.js'
@@ -71,13 +72,22 @@ export interface ActionsDriverOptions {
   now?: () => number
   /** Sleep override for tests. Default a real timer. */
   sleep?: (ms: number) => Promise<void>
+  /**
+   * Unique tag mixed into the correlation id. Default a random token; injected in tests for
+   * a stable id. Without it a fresh driver process restarts the session counter at 1, so
+   * every run's first turn is `actions-1-turn-1` and runs collide (see {@link ActionsSession}).
+   */
+  runTag?: () => string
 }
 
 /** The slice of `fetch` this driver uses. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>
 
 let sessionCounter = 0
 
+/** A short random tag so correlation ids stay unique across driver processes. */
+const randomRunTag = (): string => randomUUID().slice(0, 8)
+
 /** One Actions-backed session. Each `prompt` is one workflow run. */
 export class ActionsSession implements DriverSession {
   readonly id: string
@@ -93,7 +103,9 @@ export class ActionsSession implements DriverSession {
     private readonly startOpts: DriverStartOptions,
   ) {
     this.cwd = startOpts.cwd
-    this.id = `actions-${++sessionCounter}`
+    // The counter reads well in logs within one process; the random tag is what keeps the
+    // correlation id unique across processes, since the daemon spawns a fresh one per run.
+    this.id = `actions-${++sessionCounter}-${(config.runTag ?? randomRunTag)()}`
     this.lastSessionId = startOpts.resumeSessionId
   }
 
@@ -107,8 +119,9 @@ export class ActionsSession implements DriverSession {
     const prompt = framing ? `${framing}\n\n${text}` : text
     emit({ type: 'start', prompt })
 
-    // Deterministic, so no clock or randomness leaks into the correlation: the
-    // dispatch API returns no run id, and this is how we find our run among others.
+    // How we find our run: the dispatch API returns no run id, so the workflow echoes this
+    // into its run-name and artifact name and we match on it. It must be unique per run (the
+    // session's random tag) so a fresh process never latches onto a stale same-named run.
     const correlationId = `${this.id}-turn-${++this.turnCounter}`
     const resume = opts.resume ? this.lastSessionId : undefined