Problem

MCP_GATEWAY_SESSION_TIMEOUT controls how long stateful MCP sessions survive in both unified and routed modes. The default was recently raised from 30 minutes to 6 hours (gh-aw-mcpg#4849), but there is no way for workflow authors to configure this per-workflow. The only knob is an environment variable on the gateway container.

Long-running workflows (e.g. multi-hour code migrations, large-scale refactoring) may need longer timeouts, while short-lived workflows might benefit from shorter ones to free resources sooner. Today, all workflows sharing a gateway instance get the same timeout.

Proposal

1. Frontmatter field

Add an optional session_timeout field under tools.github (or at the top-level gateway scope) in the workflow .md frontmatter:

---
tools:
  github:
    repos: "myorg/*"
    min-integrity: approved
    session-timeout: 4h
---

Or alternatively at a top-level gateway config scope:

---
gateway:
  session-timeout: 4h
tools:
  github:
    repos: "myorg/*"
---

The value should accept Go duration strings (e.g. 30m, 1h, 4h, 6h).

2. Compiler produces gateway config

When gh aw compile processes the frontmatter, it should emit the session_timeout value into the gateway config JSON that is passed to awmg on stdin. This is the same JSON config that already carries mcpServers, guard policies, etc.

3. MCPG gateway config spec update

The MCPG stdin JSON config schema needs a new field, e.g.:

{
  "gateway": {
    "session_timeout": "4h"
  },
  "mcpServers": { ... }
}

The gateway should read this field and use it instead of the MCP_GATEWAY_SESSION_TIMEOUT env var (env var would remain as a fallback/override for infrastructure operators).

Precedence: stdin config field > environment variable > default (6h)

4. Validation

• Must be a valid Go duration string
• Should enforce reasonable bounds (e.g. minimum 5m, maximum 12h)
• gh aw compile --validate should catch invalid values

Why this matters

• Workflow authors should be able to express timeout requirements declaratively alongside their other workflow configuration
• Infrastructure operators retain override capability via the env var
• Aligns with the pattern of other gateway settings that flow from frontmatter → compiled config → stdin JSON → MCPG

Changes required