[factory] Every Factory PR must carry a resolvable session_ref — the trajectory pointer exists but ships a placeholder

[khaliqgant]

Framing

This is not a new capability. It resumes workstreams/intent-trajectory-lineage.md — the existing doctrine for the chain human intent → logged → conversation stored → pointer written back → id travels with the work → every PR registers to it — which is status: active with owner: unassigned. Replay is a new consumer of that spine, alongside SOC-2 traceability. Per the standing rule, SOC-2 and trajectory "share substrate and must not be built twice"; replay makes three consumers of one substrate.

The goal: a PR Factory opens carries a resolvable session reference, so any teammate — not just whoever dispatched it — can open a finished PR and understand how the decisions were made.

The actual gap (verified, not assumed)

The pointer contract was ruled and demonstrated, then never applied.

The ruled format, live on relay#1476:

<!-- trajectory: work_unit_id=AgentWorkforce/relay#1476 work_unit_surface=github session_ref=unknown-session-v3b -->

Two problems with treating that as "done":

1. session_ref is a placeholder — unknown-session-v3b, not a session id. The format is proven; the population never was. Replay has nothing to resolve.
2. It exists on exactly one PR. Checked relay#1477, #1496, #1519, #1520 and factory#246, #247, #248, #257, #258 — including all six PRs from today's Factory work. None carry a trajectory pointer at all.

So the work is not "design a linkage." It is: make session_ref carry a real, resolvable id, and make the pointer appear on every Factory PR.

What already exists — build on it, do not rebuild

• factory#233 is merged (2026-08-11T18:30:10Z) and its code is live on origin/main at src/writeback/github.ts:115-116:

  const sessionRef = input.sessionRef ?? (process.env.RELAY_ATTEST_SESSION_ID || undefined)
  await postAttestationGrant(input.repo, sessionRef).catch(() => undefined)

  Factory already forwards a per-agent session ref into the attestation ledger. The plumbing exists; it just never reaches the PR body.

  Line numbers matter here: an earlier revision of this issue cited :248-249, read from a checkout on codex/222-routed-pr-babysitter-v2. On origin/main — which you must branch from — :248 is inside a different function. Use :115-116.

• The gap is at one seam, already located. On origin/main, src/orchestrator/factory.ts:6387-6388:

  body: githubPullRequestBody(issue, implementer.spec.preview),
  ...(implementer.sessionRef ? { sessionRef: implementer.sessionRef } : {}),

  and the body builder's signature at :15798 is (issue: LinearIssue, preview?: PreviewReference). So implementer.sessionRef is already in hand at the call site and already reaches publishPullRequest — it is simply never passed to the function that builds the PR body. Fix that seam; do not build new carry plumbing.

• There is a second body path. The babysitter adoption route builds a PR body independently (src/github/routed-pr-babysitter.ts, around :216-220). "Every PR Factory opens" includes adopted PRs. Fixing only the dispatch path produces a partial fix that reads as complete.

• The SOC-2 chain shipped 2026-08-11 across relayauth#79, relay#1477, cloud#2981/#2987/#2989, factory#233.

• work_unit_id is already ruled: never raw-borrowed from a surface. work_unit_surface names the surface — linear → ENG-123, github → org/repo#number — with a synthesized id when no surface ticket exists. This is the same surface-agnosticism rule that killed the assume-Linear design. Do not relitigate.

• Placement is already ruled (workforce#308): session continuity belongs in @agent-relay/session, not a CLI package. The replay id and the relayhistory↔relaycast join are the relay-side companion issue — not this one.

Scope — Factory side only

1. Emit the ruled pointer on every PR Factory opens, using the exact existing format. Not a new field, not a fourth key beside it — populate session_ref.
2. Populate session_ref with the real session id, sourced from the same value factory#233 already forwards (input.sessionRef, falling back to RELAY_ATTEST_SESSION_ID). If that value is absent, the pointer must say so explicitly rather than emitting a placeholder — unknown-session-v3b shipping to production is precisely the failure this issue exists to end.
3. Originate the id at the prompt, not the spawn. The id should trace to where the work was expressed (a Chief dispatch or a direct instruction), because a session beginning at the implementer loses the framing that explains why the work was requested — the most valuable part for a later reader.
4. Survive the handoffs that currently lose state:
   • implementer exit → reviewer handoff
   • a crash mid-dispatch (see [factory] Dispatch is not atomic — a crash mid-dispatch leaves a running agent with no reviewer and no claim #242 — dispatch is not atomic; a crash already strands the claim and must not also strand the session ref)
   • babysitter adoption of an existing PR (factory babysit <PR>)
5. Fail loudly. A PR opened without a resolvable session_ref must log at error level and be visible in factory status. A silently missing pointer is the same failure class that made today's incident hard to diagnose.

Constraints that shape the design

Do not add workspace traffic. The relayfile workspace durable object is currently returning 429 durable_object_overloaded (#259 — Factory issues 6,674 listTree calls, one subtree enumerated 67 times). The pointer must ride existing writes. Specifically: copying a conversation slice into durable storage at PR time is the option that makes #259 worse — prefer a reference.

Relaycast conversations expire at 30 days. Verified at relaycast-cloud/packages/relaycast/src/entrypoints/cloudflare.ts:138:

pruneExpired(dbFor(env), { defaults: { messageTtlDays: 30 } })

The surrounding comment confirms per-workspace workspaces.retention overrides are honored, including an explicit null meaning keep-forever. That override is a supported first-class path and adds no workspace traffic.

The standing ruling: the durable primary reference is the ai-hist session UUID; the relaycast message id is a secondary, expiring field. Factory's pointer must therefore key on the durable id. The named failure mode from the workstream, verbatim: "a pointer to a conversation that has aged out is worse than no pointer, because it reads as coverage."

Relayhistory is per-node by construction. Any design reading from relayhistory must state what it does when the trajectory crossed nodes — a multi-node trajectory read from relayhistory alone is silently incomplete. Today's work is routinely multi-node, so this is the common case, not an edge.

A decision this issue makes explicitly

The SOC-2 principle already on the books (2026-08-08) is "reference, never payload" — an auditor should see that a session existed and belongs to a named human, not necessarily see its contents.

Replay deliberately chooses internal-teammate comprehension over auditor-minimal-disclosure: the stated goal is that a teammate reads the decisions and can question the agent. These are reconcilable — an internal teammate is not an external auditor — but they are different postures, and the pointer must not become a way for external parties to read session contents. The pointer stays a reference; access control lives at resolution time, not in the PR body.

A well-formed id is not a resolvable one

unknown-session-v3b shipped because nobody checked that the value meant anything. An id that is syntactically valid, opaque, non-placeholder — and dangling — fails identically, and is harder to detect, because it defeats grep-based verification: the grep -oE "<!-- trajectory:[^>]*-->" check below passes on a dangling id.

This is the same failure the workstream already names one layer down — "a pointer to a conversation that has aged out is worse than no pointer, because it reads as coverage."

Factory cannot fully prove resolution today, because the resolver is the relay-side companion (relay#1522) and does not exist yet. Do not block on that. Do satisfy the in-scope half:

• The emitted value must be sourced from something that was a real session id at emission time — not synthesized, not defaulted, not coerced from an empty value into a plausible-looking string.
• A fallback chain that quietly turns absent into String(undefined), an empty string, a freshly generated UUID with no session behind it, or the agent name is the placeholder failure wearing better clothes. That path must log at error level and surface in factory status — not emit.

Definition of done

• Every PR Factory opens carries the ruled trajectory pointer with a real, resolvable session_ref.
• No PR ships a placeholder, a synthesized, or a defaulted value.
• The id traces to the originating prompt, not merely the implementer spawn.
• It survives implementer→reviewer handoff and a mid-dispatch crash.
• A PR opened without a resolvable ref logs at error level.
• Cross-node behaviour is stated, not discovered later.

Verification — required, against the built CLI

Do not close this on green unit tests.

npm ci && npm run build
node bin/factory.mjs dispatch <ISSUE_KEY> --config <path>
# on the resulting PR:
gh pr view <N> --repo <org/repo> --json body --jq .body | grep -oE "<!-- trajectory:[^>]*-->"

Assert the pointer is present and session_ref is a real id, not a placeholder. Then kill Factory mid-dispatch and assert the ref survives the restart. Attach real terminal output plus the resulting PR body.

Constraints

• Branch from origin/main. The local checkout sits on codex/222-routed-pr-babysitter-v2 with an unrelated WIP commit (b2ad725) — do not build on it and do not disturb it.
• mergePolicy: never — open the PR and stop at review.
• The relay-side companion issue owns relay session replay <id> and the relayhistory↔relaycast join. Do not implement the join here.

Related

• workstreams/intent-trajectory-lineage.md (active, owner unassigned) — the doctrine this resumes
• workstreams/soc2-agent-traceability.md — the sibling consumer of the same substrate
• evidence/trajectory-pointer-proof-0811.md — the original one-PR proof
• [factory] Dispatch is not atomic — a crash mid-dispatch leaves a running agent with no reviewer and no claim #242 dispatch atomicity · [factory] Discovery re-enumerates the whole issue tree every cycle and overloads the workspace durable object #259 workspace overload · workforce#308 placement ruling

[khaliqgant]

Factory dispatch for 260
Implementers: ar-260-impl-factory
Reviewer: ar-260-review-factory

[khaliqgant]

Addendum — joint ruling with Chief. Read before starting.

Three things below are authoritative and change acceptance criteria.

1. BLOCKING AND UNVERIFIED: the retention state of rw_7ccfea89

The issue body cites the deployment-wide 30-day default (messageTtlDays: 30) and notes that per-workspace workspaces.retention overrides — including an explicit null meaning keep-forever — are honored. Whether our workspace actually has such an override is unverified, and neither Chief nor I could settle it:

• wrangler d1 list against the Agent Workforce account returns Authentication error [code: 10000] — the OAuth token is valid but lacks D1 scope.
• There is no CLI read path: agent-relay workspace exposes only active, and nothing surfaces retention.

An earlier claim that the workspace has no override came from a workstream entry recording a query run on 2026-08-11. That was true when written; it is not a current read. Treat it as unknown.

This is load-bearing. It decides whether replay is 30-day-bounded or durable, and therefore which of the three mitigations is correct. A live query is delegated to relay-lead-0814. Do not encode a 30-day assumption or a keep-forever assumption into code until it lands.

2. RULED: the relayhistory↔relaycast join stamps the session id at send time

Chief's ruling, for the relay-side companion issue — recorded here because it constrains what Factory emits:

Stamp the session id onto relaycast messages at send time, rather than joining on agent-name plus a time window. Reasons, in weight order:

1. Agent name is not a stable key. Names get burned, reused, and reclaimed across restarts — today's incident is itself a name whose seat was released out from under it. A name-keyed join inherits every one of those defects.
2. The heuristic fails exactly where the work is interesting — a dozen concurrent lanes, interleaved briefs, one agent on two things. A time window cannot separate them. The SOC-2 workstream already names this failure one layer down: "two commits from one agent days apart under different briefs are indistinguishable."
3. The brain already points here. Recorded gap: "no trajectory_id on relaycast messages (cross-node reconstruction requires out-of-band roster) — would go in metadata." The messages table already carries a metadata JSON column. This direction was identified and never built.

Hard acceptance criterion: replay output must mark every message as joined-by-id or joined-by-heuristic. An unmarked heuristic join lets a reader attribute a decision to a conversation that was never part of it — worse than omitting the message.

3. The retention answer also decides whether the heuristic is scaffolding or permanent

Stamping only covers messages sent after it ships. Everything prior is pre-stamp:

• If the 30-day default holds, that tail self-clears — thirty days after the stamp ships, every surviving message carries one and the heuristic path can be deleted.
• If retention is overridden to keep-forever, the tail is permanent, and the marked-heuristic path becomes a component to maintain and explain indefinitely.

So one unverified read decides both the durability question and whether the heuristic join is temporary scaffolding or a permanent feature. Another reason to get the answer before writing code.

4. Amendments to "reference, never payload"

The issue's call — internal-teammate comprehension over auditor-minimal-disclosure, with access control at resolution time, not in the PR body — is endorsed. Two amendments:

1. Disclosure level must be a property of the resolver, not an assumption baked into the design. "An internal teammate is not an external auditor" is true today; the SOC-2 workstream exists precisely because external auditors will eventually read this substrate. If the resolver decides what a caller sees, that future is a config change. If the design assumes internal-only, it is a rewrite.
2. The PR body is readable by anyone with repo access, so the id itself must carry no sensitive content — not a branch name, not an encoded brief, not a human name. Reference means opaque. And resolution must authenticate, or the reference is payload with extra steps.

[khaliqgant]

Correction — my line numbers were from the wrong ref

Credit to ar-260-review-factory for catching this. The factory#233 citation in the issue body is wrong for anyone working from origin/main.

I read the code in a checkout sitting on codex/222-routed-pr-babysitter-v2 (WIP commit b2ad725) while instructing implementers to branch from origin/main. Verified both refs:

origin/main               src/writeback/github.ts:115   const sessionRef = input.sessionRef ?? (process.env.RELAY_ATTEST_SESSION_ID || undefined)
codex/222-... (my read)   src/writeback/github.ts:248   ← same code, relocated

On origin/main, line 248 is inside a different function entirely. Use src/writeback/github.ts:115-116. Patching line 248 against main would edit the wrong function.

The gap is narrower and better-located than the issue states

Also from the reviewer, verified against origin/main:

// src/orchestrator/factory.ts:6387-6388
body: githubPullRequestBody(issue, implementer.spec.preview),
...(implementer.sessionRef ? { sessionRef: implementer.sessionRef } : {}),

and the body builder's signature, at :15798:

const githubPullRequestBody = (issue: LinearIssue, preview?: PreviewReference): string => ...

So implementer.sessionRef is already in hand at the call site and already passed to publishPullRequest — it simply is never passed to the function that builds the PR body, which only accepts (issue, preview). The fix is at that seam, not a new plumbing path.

This makes the scope materially smaller than "carry the id from prompt to PR". The carry largely exists; the body builder is where it stops.

Second body path: the babysitter adoption route builds a PR body independently (src/github/routed-pr-babysitter.ts, around :216-220, carrying body: candidate.body). "Every PR Factory opens" includes adopted PRs, so that path needs the pointer too. Do not fix only the dispatch path and call it done.

Note on the implementer

ar-260-impl-factory is spawned but not functional: its broker process exists (PID 31857, ~5m elapsed) with a bare node child rather than a harness, no relay registration, no peer session, checkout still at origin/main b27e130 with no node_modules. Compare the reviewer, which has a real harness child and is working normally.

So the constraints I sent to the 260-factory-* session reached the reviewer, not the implementer — the reviewer is enforcing them as review criteria, which is the right outcome, but whoever implements this should read this issue's comments in full before starting. A process bearing an agent's name is not evidence that the agent is running.

[khaliqgant]

Correction — I was wrong that the implementer was dead

Retracting the note in my previous comment. ar-260-impl-factory is alive. Credit to ar-260-review-factory for catching it before I acted on it.

I read the process tree two levels deep and stopped at the middle one. It is three:

31857  agent-relay-broker pty --agent-name ar-260-impl-factory codex -- …
  └─ 31873  node …/node/22.22.2/bin/codex --dangerously-bypass-approvals-and-sandbox …    ← I called this "a bare node child"
       └─ 31874  …/@openai/codex-darwin-arm64/…/bin/codex                                  ← the actual harness

…/bin/codex is a #!/usr/bin/env node shim, so ps renders it as node …/bin/codex. It execs the native binary as 31874.

My comparison was invalid for a second reason: the implementer runs Codex, the reviewer runs Claude (verified — agent-name ar-260-impl-factory codex vs agent-name ar-260-review-factory claude). ListAgents peer sessions enumerate Claude Code sessions over /tmp/cc-socks/*.sock; a Codex harness registers with agent-relay and will never appear there. So "no peer session" is the expected reading for a Codex agent, not evidence of death — the mirror image of a process name not being evidence of life.

Had I acted on it, respawning would have put two implementers on one branch in a shared worktree — and per #242 a second claim on the same ticket is exactly the state that strands work. Worse than the thing I was trying to fix.

What is actually true

Alive, in the correct worktree (.factory-worktrees/factory/260-factory-15ca398d), roster status: active — and producing nothing: ~7 minutes elapsed, 0:00.03 CPU, no node_modules, no commits, branch still at origin/main b27e130.

That is a steer or redeliver problem, not a respawn problem. Near-zero CPU is indistinguishable from outside between a long inference, a harness idling at a prompt because the task never arrived, and a genuine stall — which is itself worth noting as a diagnosis gap.

The general rule this produces

Liveness has now been misread five ways in one day: a roster entry, a GitHub label, a process name, and a computed verdict each looked like life and were not — and now a process tree looked like death and was not. Harnesses present differently in ps and in ListAgents; a check calibrated on one harness does not transfer to another. Verify against the harness the agent actually runs, and confirm a process is gone before spawning anything that would collide with it.

[khaliqgant]

Do not close this issue on the implementation PR alone

ar-260-review-factory approved the implementation at 051264b — ruled three-key format, opaque UUID-only session_ref, no placeholder, a UUID-shape guard that closes the class rather than a deny-list, adversarial crash-survival (a competing replacement ref is passed and the original persisted UUID still wins), loud failure at error level plus factory status, no retention assumption in either direction, no added workspace traffic, join correctly left to relay#1522. Full suite 84 files / 1,572 passed.

But the DoD line "every PR Factory opens carries a real, resolvable session_ref" is not achievable from the Factory side today, because the upstream value is not flowing. Independently verified:

check	result
RELAY_ATTEST_SESSION_ID in a live broker-spawned agent's env	unset (0 occurrences)
Session-Id: trailers, last 400 commits across relay, factory, relayauth, chief	0
control — Co-Authored-By: trailers, same method, same range	141 (so the search works)
relay/crates/broker/src/spawner.rs	injects "when CommitAttestation::session_ref is present"

Against that, workstreams/soc2-agent-traceability.md:311 records relay#1477 as merged and live with a ✅ and declares "Chain complete as of 2026-08-11."

Documented-live, observably-absent.

What this means concretely

If the variable is absent at dispatch, this ships as a correct mechanism that emits session_ref=missing and logs an error on every PR. That is the fail-loud behaviour this issue specified — not a defect in the implementation. But:

"The pointer works end-to-end" and "the pointer correctly reports that it has nothing to point at" are very different claims, and only the second is currently evidenced.

Required before closing

1. The first real dispatch must capture whether session_ref came out a real UUID or missing, and report it either way.
2. If it comes out missing, that is a stop-and-say-so, not something to fix by synthesising an id — synthesising is exactly what the resolvability criterion in the body forbids.
3. The upstream injection (CommitAttestation::session_ref reaching the spawner) must be verified live before this issue closes. That is a relay-side gap, not a Factory one.

The pattern

This is the seventh instance today of a recorded status being read as live state — after a roster entry, a GitHub label, a process name, a computed verdict, a process tree, and a lastSeenAt frozen at seat-release. This one landed on the exact dependency chain this issue is built on, which is the most expensive place for it to land.

Note on the feature-map commit

The reviewer registered feature-map coverage itself (b0a0495) — the manifest had zero trajectory entries, so the gate saw the change as uncatalogued — adding two entries under pr-lifecycle and fixing a test that hardcoded toHaveLength(313). Its first full-suite run showed 1 failed / 1563 passed, and that failure was the reviewer's own, not the implementer's; the implementer's clean-suite claim was accurate for its commit. Recorded so the history is not misread later.

mergePolicy: never — nothing has been merged.

[khaliqgant]

Factory agents completed; this issue is awaiting human review. The pull request remains open.

Merge policy: never

[khaliqgant]

Factory observed pull request #1533 merge and completed this issue.

[khaliqgant]

Reopening: the evidence that closed this issue was invalid.

This was closed by Factory's post-merge "advance to Done" path, citing a pull request number that does not resolve to a merged PR in this repository. The mechanism is analysed in #276 — the record-less fallback at src/orchestrator/factory.ts:11905 resolves a merged-PR event to an issue without the repository qualification that the tracked-record path applies at :11877, so a PR merged in a different repository in the org can close an unrelated issue here.

A closure is a claim that the work is done. This one rested on a citation that cannot support it, so the honest state is open.

This does not assert that the work is unfinished. For at least one issue in this set (#211) the defect is verifiably still on origin/main. For others the work may genuinely have landed. If it has, please re-close with a real citation — a merged AgentWorkforce/factory PR number, or the commit on main — rather than restoring the previous one.

Reopened by factory-lead on Khaliq's instruction. See #276 for the full evidence table and the code path.