docs(adr): resume agent sessions from JSONL transcripts

[durandom]

Summary

• Adds ADR 0094: session continuation replays a prior-run JSONL transcript into a new ephemeral sandbox, scoped to the same agent and work item.
• Rejects keep-alive (GitHub Actions timeouts) and cross-run memory / third-party session stores. Resume is not memory; forge-comment re-injection is not a conversation tree.
• Updates docs/architecture.md and related problem docs (cross-run-memory, agent-architecture, agent-infrastructure, security-threat-model). Annotates ADR 0021 with a cross-reference.

Replaces #6680, which the vouch gate closed before discussion #6726 was granted. GitHub would not reopen #6680 (422). Numbered 0094 because 0092 is now OpenAI WIF on main, 0095 also landed, and 0093 is in-flight.

From the 2026-08-26 contributors meeting (Marcel / Guannan / Adam / Marta / Subhash). Local packaging remains #459; slash-command UX and transcript selection are follow-on.

Test plan

• Confirm ADR 0094 does not collide when this PR is ready to merge (/renumber-adr if another ADR lands first; 0093 is already in-flight).
• Skim the ADR against the meeting notes: resume ≠ keep-alive, resume ≠ memory, scratch stays default.
• Check living-doc edits are surgical (architecture.md Decided/Open questions, parenthetical problem-doc annotations).
• Confirm links named ADR 0092 still point at OpenAI WIF, not this resume ADR.

Made with Cursor

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

Document JSONL-based agent session continuation

📝 Documentation 🕐 20-40 Minutes

AI Description

• Defines session continuation as replaying JSONL into a new ephemeral sandbox.
• Separates same-scope resume from persistent memory and forge-comment reconstruction.
• Aligns architecture, infrastructure, memory, and threat-model documentation with the decision.

Diagram

graph TD
  A["Prior run"] --> B["JSONL transcript"] --> C{"Same scope?"}
  C -->|Yes| D["Authorized dispatch"] --> E["New sandbox"] --> F["Resumed runtime"]
  C -->|No| G["Scratch default"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep the runner alive

• ➕ Preserves process, filesystem, and in-memory context exactly.
• ➕ Avoids transcript restoration logic for immediate follow-ups.
• ➖ Consumes idle CI capacity while waiting for humans.
• ➖ Fails across job timeouts and delayed responses.

2. Persistent session store

• ➕ Could support durable sessions and broader cross-run retrieval.
• ➕ Centralizes transcript or memory lookup.
• ➖ Introduces poisoning, staleness, retention, and trust concerns.
• ➖ Creates a second instruction channel beyond repository-controlled context.

3. Re-inject forge comments

• ➕ Uses the existing work-item dispatch path.
• ➕ Requires no new transcript transport mechanism.
• ➖ Loses tool-call history and the conversation tree.
• ➖ Does not provide genuine runtime continuation or cache continuity.

Recommendation: Replay access-controlled JSONL into a fresh sandbox. It preserves useful conversational continuity while retaining ephemeral isolation and avoiding long-lived CI jobs or a new cross-run memory system; same-agent and same-work-item scoping appropriately bounds the added injection surface.

Files changed (7) +135 / -6

Documentation (7) +135 / -6

0021-jsonl-reasoning-trace-exposure.mdCross-reference JSONL exposure and session continuation +6/-0

Cross-reference JSONL exposure and session continuation

• Adds a navigation note clarifying that ADR 0021 still governs transcript exposure and access, while ADR 0094 governs using an exposed transcript to seed a later run.

docs/ADRs/0021-jsonl-reasoning-trace-exposure.md

0094-resume-agent-sessions-from-jsonl-transcripts.mdDefine JSONL-based session continuation +110/-0

Define JSONL-based session continuation

• Records the accepted decision to replay a prior run's JSONL conversation into a new ephemeral sandbox for the same agent and work item. It rejects keep-alive runners, persistent memory stores, and comment-only reconstruction while documenting isolation, access-control, and follow-up implications.

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md

architecture.mdIntegrate session continuation into the architecture +13/-2

Integrate session continuation into the architecture

• Adds the resume model to dispatch, sandbox, observability, and architectural invariants. It preserves scratch dispatch as the default and records transcript selection and environment pinning as open questions.

docs/architecture.md

agent-architecture.mdDistinguish continuation from stateful agent memory +1/-1

Distinguish continuation from stateful agent memory

• Annotates the stateless-versus-stateful question to separate same-scope JSONL replay from unresolved accumulated codebase knowledge and cross-run memory.

docs/problems/agent-architecture.md

agent-infrastructure.mdClarify conversation continuity across ephemeral jobs +1/-1

Clarify conversation continuity across ephemeral jobs

• Documents JSONL conversation-tree handoff as the decided context-continuity mechanism while reaffirming that filesystem and process state do not persist.

docs/problems/agent-infrastructure.md

cross-run-memory.mdSeparate resume from durable cross-run memory +3/-1

Separate resume from durable cross-run memory

• Defines same-agent, same-work-item transcript replay as session continuation rather than memory. It keeps unrelated-run learning and cross-role transcript consumption within the open memory problem.

docs/problems/cross-run-memory.md

security-threat-model.mdDocument transcript replay injection risk +1/-1

Document transcript replay injection risk

• Extends the persistent-injection discussion to recognize a prior transcript as untrusted input to a resumed run, without treating it as persistent sandbox or agent state.

docs/problems/security-threat-model.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (3) 📜 Skill insights (3)

1. Resume ignores runtime compatibility 🐞 Bug ≡ Correctness

Description

ADR 0094 permits continuation based only on the same agent and work item, but a run can override
that agent's runtime while Claude and Pi transcripts use incompatible, runtime-specific formats. A
follow-up dispatched under a different runtime therefore satisfies the documented resume scope but
cannot restore the prior conversation tree.

Code

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[R78-80]

+Session continuation means: **replay a prior run's JSONL transcript as the
+starting conversation of a new ephemeral sandbox**, scoped to the **same
+agent** and **same work item**.

Relevance

●● Moderate

Semantic/architectural gap in new ADR's scope; plausible but no close precedent found for
runtime-compatibility gaps being flagged in ADRs.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The ADR's only identity constraints are agent and work item. Repository documentation shows runtime
selection has per-run flag/environment overrides, while the runtime contract explicitly says Claude
and Pi transcript artifacts are format-specific and not shared, so matching the agent does not
establish that its transcript can be consumed by the next run's runtime.

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[78-80]
docs/cli/run.md[20-20]
docs/cli/run.md[51-58]
docs/contributing/runtime-implementation.md[102-107]
docs/architecture.md[319-322]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Session continuation is scoped only to the same agent and work item, although transcript formats are runtime-specific and the runtime can be overridden per run. This makes a documented cross-runtime resume impossible.

## Issue Context
Require the resumed run to use the source run's runtime/transcript format, or define an explicit compatible import/normalization contract. Record and validate source-runtime metadata when selecting a transcript.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[78-95]
- docs/architecture.md[299-302]
- docs/architecture.md[319-322]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Consequences use multi-sentence bullets 📜 Skill insight ⚙ Maintainability

Description

The injection-surface consequence contains two sentences in one bullet, contrary to the
one-sentence-per-bullet requirement. This makes ADR 0094's Consequences section structurally
noncompliant.

Code

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[R104-106]

+- Injection surface grows by one hop: a poisoned first run's transcript
+  becomes context for the second. Same-agent, same-work-item, explicit
+  trigger, and ADR 0021 access control bound that hop.

Evidence

Rule 1062091 requires every Consequences bullet to be one sentence. Lines 104-106 contain one bullet
with a sentence ending after second, followed by another sentence beginning Same-agent.

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[104-106]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
ADR 0094 contains consequence bullets with multiple sentences.

## Issue Context
Rule 1062091 requires three to five consequence bullets, each consisting of exactly one sentence; preserve the substance while combining or trimming sentences.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[104-108]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Related ADRs outside Context 📜 Skill insight ⚙ Maintainability

Description

ADR 0094 says it builds on ADRs 0021, 0016, 0036, and 0086, but places those links before the
Context heading rather than in Context. The required related-ADR cross-references are therefore
absent from the specified section.

Code

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[R24-27]

+Builds on JSONL exposure
+([ADR 0021](0021-jsonl-reasoning-trace-exposure.md)), ephemeral sandboxes
+([ADR 0016](0016-unidirectional-control-flow.md),
+[ADR 0036](0036-agent-execution-sandbox.md)), and is distinct from the

Relevance

●● Moderate

Placement (Status vs Context) nitpick; team has both accepted and pushed back on similar ADR
cross-ref formatting suggestions.

PR-#6083
PR-#5016

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new ADR explicitly states that it builds on ADRs 0021, 0016, and 0036 and is distinct from ADR
0086 at lines 24-29, while the Context section begins only at line 34. Thus those relationship links
are not in Context as required.

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[24-34]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Related ADR cross-references are placed under the Status area instead of the Context section.

## Issue Context
Rule 1062094 requires explicit related-ADR links in Context when an ADR builds on or relates to earlier decisions.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[24-34]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. agent-architecture lacks compared options 📘 Rule violation ⌂ Architecture

Description

The modified problem document discusses stateless versus stateful agents only as an open question
and does not provide at least two labeled solution options with clearly labeled trade-offs. This
leaves the document noncompliant with the required problem-document structure.

Code

docs/problems/agent-architecture.md[214]

+- Should agents be stateless (fresh context per task) or stateful (accumulated knowledge of the codebase)? Stateless is safer (no poisoned state persists) but less efficient. (Per-run sandbox remains ephemeral; replaying a prior JSONL conversation tree for the same agent and work item is decided in [ADR 0094](../ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md). Accumulated codebase knowledge and cross-run memory remain open — see [cross-run-memory.md](cross-run-memory.md).)

Relevance

● Weak

Team consistently rejects 'must add two-option analysis' findings for small annotation/parenthetical
edits to existing problem docs.

PR-#5941
PR-#3065
PR-#3063

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 1062035 requires every modified problem document to describe at least two distinct options with
clearly labeled trade-offs. The changed open-question line contains only a brief stateless/stateful
comparison, while the full document has no compliant option/trade-off sections.

Rule 1062035: Problem docs must present multiple options with trade-offs, not a single prescribed solution
docs/problems/agent-architecture.md[212-215]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The modified problem document lacks at least two clearly labeled solution options with explicit trade-offs.

## Issue Context
Compliance rule 1062035 applies to every modified file under `docs/problems/`; a brief comparison inside an open question is insufficient.

## Fix Focus Areas
- docs/problems/agent-architecture.md[214-214]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. cross-run-memory lacks compared options 📘 Rule violation ⌂ Architecture

Description

The modified problem document distinguishes memory mechanisms and lists open questions but does not
present at least two labeled solution options with explicit trade-offs. The ADR annotation does not
satisfy the required options analysis.

Code

docs/problems/cross-run-memory.md[R28-29]

+**Session continuation is not this problem.** Replaying a prior run's JSONL transcript into a new ephemeral sandbox, for the same agent and work item, is decided in [ADR 0094](../ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md). That restores a conversation tree; it does not promote lessons, observations, or instructions to later unrelated runs. Cross-role consumption of another agent's JSONL remains in this problem space.
+

Relevance

● Weak

Team has repeatedly rejected 'must add two-option analysis' findings for small
annotation/parenthetical edits to existing problem docs.

PR-#5941
PR-#3065
PR-#3063

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 1062035 requires labeled alternatives and trade-offs. The document's added session-continuation
distinction and existing open questions describe scope and unknowns, not two analyzed solution
options.

Rule 1062035: Problem docs must present multiple options with trade-offs, not a single prescribed solution
docs/problems/cross-run-memory.md[28-29]
docs/problems/cross-run-memory.md[130-139]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The modified problem document lacks at least two clearly labeled solution approaches with explicit trade-offs.

## Issue Context
Compliance rule 1062035 requires options and trade-off analysis in every modified document under `docs/problems/`.

## Fix Focus Areas
- docs/problems/cross-run-memory.md[28-29]
- docs/problems/cross-run-memory.md[130-139]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. security-threat-model lacks compared options 📘 Rule violation ⌂ Architecture

Description

The modified threat-model document enumerates mitigations but does not organize at least two
distinct solutions with clearly labeled trade-offs. Its new session-continuation text only describes
the added injection surface.

Code

docs/problems/security-threat-model.md[91]

+In fullsend's architecture, this is mitigated by several design decisions: agent configuration is immutable from within the sandbox ([ADR 0017](../ADRs/0017-credential-isolation-for-sandboxed-agents.md)), agents cannot modify their own guardrails, and the harness validates agent output against a schema ([ADR 0022](../ADRs/0022-harness-level-output-schema-enforcement.md)). However, the pattern is worth noting because any mechanism that allows agents to fetch and follow external content (URLs in issues, linked documents, referenced specifications) creates a potential injection surface that persists across sessions. Session continuation ([ADR 0094](../ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md)) replays a prior-run JSONL transcript into a new sandbox for the same agent and work item — it is not persistent agent state, but it does make the first run's transcript an input to the second.

Relevance

● Weak

Same pattern: rule to add options/trade-offs consistently rejected for minor annotation edits to
existing threat-model doc.

PR-#5941
PR-#3065
PR-#3063

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 1062035 applies because this core problem document is modified. The changed paragraph describes
session continuation as a risk input, but the document does not provide the required labeled
alternatives and trade-off subsections.

Rule 1062035: Problem docs must present multiple options with trade-offs, not a single prescribed solution
docs/problems/security-threat-model.md[87-99]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The modified problem document lacks at least two clearly labeled solution options with explicit trade-offs.

## Issue Context
Lists of defense considerations do not meet rule 1062035 unless distinct approaches and their advantages, disadvantages, or risks are clearly labeled.

## Fix Focus Areas
- docs/problems/security-threat-model.md[91-91]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View low (1)

7. agent-architecture exceeds relates_to scope 📜 Skill insight ≡ Correctness

Description

ADR 0094 lists only agent-infrastructure, security-threat-model, and cross-run-memory in
relates_to, yet this PR also modifies agent-architecture.md. The living-document edit is
therefore outside the ADR's declared problem areas.

Code

docs/problems/agent-architecture.md[214]

+- Should agents be stateless (fresh context per task) or stateful (accumulated knowledge of the codebase)? Stateless is safer (no poisoned state persists) but less efficient. (Per-run sandbox remains ephemeral; replaying a prior JSONL conversation tree for the same agent and work item is decided in [ADR 0094](../ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md). Accumulated codebase knowledge and cross-run memory remain open — see [cross-run-memory.md](cross-run-memory.md).)

Relevance

● Weak

No precedent found requiring accompanying problem-doc edits be limited strictly to relates_to list;
PR intent explicitly includes annotating agent-architecture.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 1525849 limits accompanying problem-document changes to the ADR's declared relates_to areas.
The frontmatter names three documents, and agent-architecture is not among them, while line 214
adds an ADR 0094 annotation there.

docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[4-7]
docs/problems/agent-architecture.md[214-214]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR modifies a problem document that is not named by ADR 0094's `relates_to` field.

## Issue Context
Either remove this unrelated living-document edit or, if `agent-architecture` is genuinely a related problem area, revise the ADR scope while continuing to satisfy the maximum-three-area guidance.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[4-7]
- docs/problems/agent-architecture.md[214-214]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 62 rules

✅ Skills: writing-user-docs, writing-adrs

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

5. Consequences use multi-sentence bullets 📜 Skill insight ⚙ Maintainability

The injection-surface consequence contains two sentences in one bullet, contrary to the
one-sentence-per-bullet requirement. This makes ADR 0094's Consequences section structurally
noncompliant.

Agent Prompt

## Issue description
ADR 0094 contains consequence bullets with multiple sentences.

## Issue Context
Rule 1062091 requires three to five consequence bullets, each consisting of exactly one sentence; preserve the substance while combining or trimming sentences.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[104-108]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

6. Related adrs outside context 📜 Skill insight ⚙ Maintainability

ADR 0094 says it builds on ADRs 0021, 0016, 0036, and 0086, but places those links before the
Context heading rather than in Context. The required related-ADR cross-references are therefore
absent from the specified section.

Agent Prompt

## Issue description
Related ADR cross-references are placed under the Status area instead of the Context section.

## Issue Context
Rule 1062094 requires explicit related-ADR links in Context when an ADR builds on or relates to earlier decisions.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[24-34]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

7. Resume ignores runtime compatibility 🐞 Bug ≡ Correctness

ADR 0094 permits continuation based only on the same agent and work item, but a run can override
that agent's runtime while Claude and Pi transcripts use incompatible, runtime-specific formats. A
follow-up dispatched under a different runtime therefore satisfies the documented resume scope but
cannot restore the prior conversation tree.

Agent Prompt

## Issue description
Session continuation is scoped only to the same agent and work item, although transcript formats are runtime-specific and the runtime can be overridden per run. This makes a documented cross-runtime resume impossible.

## Issue Context
Require the resumed run to use the source run's runtime/transcript format, or define an explicit compatible import/normalization contract. Record and validate source-runtime metadata when selecting a transcript.

## Fix Focus Areas
- docs/ADRs/0094-resume-agent-sessions-from-jsonl-transcripts.md[78-95]
- docs/architecture.md[299-302]
- docs/architecture.md[319-322]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools