test(sessions): lock down workflow resume filtering

[lavaman131]

Summary

Preserves the invariant that workflow-stage sessions remain available to workflow recovery and diagnostics without polluting normal session history. The runtime behavior was already present; this PR closes the remaining regression-coverage and documentation gaps across every user-facing resume surface.

Changes

• Adds an end-to-end resume-surface regression suite covering:
  • interactive /resume
  • startup atomic -r and atomic --resume
  • atomic -c and atomic --continue
  • SessionManager.list, SessionManager.listAll, and SessionManager.continueRecent
• Exercises a mixed history with one regular session and 64 internal workflow-stage sessions.
• Verifies regular sessions remain visible and selectable while newer internal stages stay hidden by default.
• Verifies explicit includeInternal discovery and retained workflow run/stage metadata.
• Directly tracks transcript reads to prove default listing filters internal sessions from lightweight headers before full transcript parsing.
• Documents current SessionManager creation, listing, continuation, direct-open, and workflow metadata APIs.

Acceptance Criteria Coverage

• Workflow-stage orchestration context is stamped as internal with run/stage linkage by the existing SDK path, covered by the existing SDK session-manager regression.
• All normal resume and continuation surfaces are now covered against default internal-session filtering.
• Mixed-history tests assert ordinary sessions remain available.
• Explicit internal opt-in and direct workflow linkage remain available for recovery and inspection.
• The high-volume regression proves internal transcript bodies are not fully read during normal history loading.
• No /workflow resume sorting or deduplication behavior is changed.

Validation

• Focused session/resume suite: 49 tests passed
• Pre-commit and pre-push unit suite: passed
• bun run typecheck: passed
• bun run lint: passed
• bun run check:file-length: passed
• Coding-agent docs link validation: passed
• git diff --check: passed

Fixes #1715

Greptile Summary

This PR tightens workflow-owned session handling across resume and subagent paths. The main changes are:

• Validates workflow session classification with exact internal: true and complete workflow metadata.
• Hides classified workflow sessions from normal /resume, -r, -c, --continue, SessionManager.list, and SessionManager.listAll surfaces by default.
• Preserves explicit internal discovery and direct session opening for workflow recovery and diagnostics.
• Propagates workflow metadata into workflow stage forks, foreground subagents, background subagents, and resumed child sessions.
• Adds tests and docs for mixed regular/internal histories, malformed legacy markers, and transcript-read filtering.

Confidence Score: 5/5

Safe to merge with minimal risk.

The change is focused on session classification, filtering, and metadata propagation. The updated paths use strict validation helpers and preserve explicit recovery access. Tests cover CLI, interactive, SessionManager, workflow, and subagent behavior.

No files require special attention.

T-Rex Logs

What T-Rex did

• Validated the coding-agent-resume-suite run, which completed with exit code 0 after 6s and reported 3 test files passed and 55 tests passed.
• Validated the root-session-persistence-suite run, which completed with exit code 0 after 2s and ran 20 tests across 4 files with 0 failures.
• Prepared and linked two log artifacts for reviewer inspection to verify the runs.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
packages/coding-agent/src/core/session-manager-classification.ts	Introduces shared helpers for exact internal workflow metadata validation and env parsing.
packages/coding-agent/src/core/session-manager-list.ts	Prefilters classified workflow sessions from normal list/listAll surfaces before full transcript parsing.
packages/coding-agent/src/main-session.ts	Adds inherited workflow classification application for sessions created under workflow metadata env.
packages/coding-agent/test/internal-session-resume-surfaces.test.ts	Adds broad tests for resume, continue, list, listAll, and transcript-read filtering behavior.
packages/subagents/src/runs/shared/pi-args.ts	Serializes workflow session metadata into child Atomic CLI environment variables.
packages/subagents/src/shared/types-depth.ts	Adds workflow session metadata extraction and environment helper utilities alongside depth helpers.
packages/workflows/src/runs/foreground/stage-runner-options.ts	Centralizes workflow session classification and orchestration context when creating stage sessions.
test/unit/subagents-workflow-session-persistence.test.ts	Adds workflow/subagent persistence tests for internal metadata propagation and filtering.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant WorkflowStage as Workflow stage
participant SessionManager as SessionManager
participant Subagent as Subagent launcher
participant ChildAtomic as Child Atomic process
participant Resume as Resume/list surfaces

WorkflowStage->>SessionManager: create/open/fork with internal + workflow metadata
SessionManager->>SessionManager: validate runId, stageId, stageName
WorkflowStage->>Subagent: launch child with orchestration context
Subagent->>ChildAtomic: set ATOMIC_WORKFLOW_SESSION_METADATA
ChildAtomic->>SessionManager: applyInheritedWorkflowSessionClassification()
Resume->>SessionManager: "list/listAll/continueRecent default includeInternal=false"
SessionManager-->>Resume: return regular sessions only
Resume->>SessionManager: "workflow diagnostics includeInternal=true"
SessionManager-->>Resume: return regular + classified workflow sessions

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant WorkflowStage as Workflow stage
participant SessionManager as SessionManager
participant Subagent as Subagent launcher
participant ChildAtomic as Child Atomic process
participant Resume as Resume/list surfaces

WorkflowStage->>SessionManager: create/open/fork with internal + workflow metadata
SessionManager->>SessionManager: validate runId, stageId, stageName
WorkflowStage->>Subagent: launch child with orchestration context
Subagent->>ChildAtomic: set ATOMIC_WORKFLOW_SESSION_METADATA
ChildAtomic->>SessionManager: applyInheritedWorkflowSessionClassification()
Resume->>SessionManager: "list/listAll/continueRecent default includeInternal=false"
SessionManager-->>Resume: return regular sessions only
Resume->>SessionManager: "workflow diagnostics includeInternal=true"
SessionManager-->>Resume: return regular + classified workflow sessions

Loading

_{Reviews (6): Last reviewed commit: "docs(changelog): keep session fixes unre..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
bastani	🟢 Ready	View Preview	Jul 12, 2026, 6:41 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.