[Epic] Product reset: durable Sessions, Automations, and trustworthy Runs

[dennisonbertram]

Product reset: durable Sessions, Automations, and trustworthy Runs

Why this matters

Open Agents already contains the hard primitives needed for the intended product: durable cloud coding sessions, persistent sandboxes, GitHub webhook ingestion, unattended coding agents, multi-step loops, run evidence, and retry/cancel controls. The product is difficult to operate because these capabilities are exposed through overlapping nouns, storage models, run models, and experimental systems.

This epic reduces the product to three primary surfaces while preserving the working execution paths:

1. Sessions — durable interactive coding workspaces.
2. Automations — repository-scoped coding instructions started manually, from GitHub/webhooks, or on a schedule. A single-step automation is today's background agent; a multi-step automation is today's loop.
3. Runs — a trustworthy, normalized view of what executed, why it executed, its current state, its evidence, and the available recovery controls.

This supersedes the product vocabulary in #409 while preserving its central technical decision: shared contracts and adapters first, a unified product view second, and any table merge only after the model is proven.

User/operator path protected

The protected end-to-end paths are:

• Connect a repository, start a cloud coding Session, leave, return, resume the same sandbox, and produce a branch or pull request.
• Receive a GitHub PR, review, issue, or check-suite event; match it to an enabled Automation; run coding work durably; and expose an inspectable Run.
• Define a deterministic series of agent steps, persist its definition snapshot, survive restarts, and make step progress and failures visible.
• Allow an operator to distinguish configured-and-passed, configured-and-failed, and not-configured/not-proven production journeys.

Product and architecture contract

Primary nouns

• Workspace: repository + branch + persistent sandbox identity. This is execution context, not a separate primary navigation surface.
• Session: an interactive conversation attached to a Workspace.
• Automation: a versioned definition containing one or more coding steps plus its triggers, permissions, verification, output contract, and limits.
• Run: one durable execution attempt with source, definition revision, repository/workspace, status, progress, events, outputs, costs, and retry/cancel state.

Product surfaces

• Sessions
• Automations
• Runs
• Settings, with advanced/experimental capabilities explicitly separated

Repositories are filters and context for those surfaces, not a competing product hierarchy. GitHub remains the system for general PR/issue administration; Open Agents should show only the GitHub context needed to configure an Automation or diagnose a Run.

Technical direction

• Keep current tables and mature source-specific executors initially.
• Introduce additive typed adapters and source-qualified references.
• Reuse/extract the existing Account Coordinator normalization rather than building another competing run ledger.
• Make status mappings explicit; unknown or skipped states must never become completed/passed.
• Keep legacy routes until parity and redirect tests exist.
• Characterize both executors before extracting shared execution primitives.
• Defer any destructive schema consolidation to a later research spike.

Behavior contract

Scenario: durable interactive work

Given a user has an active repository Session, when the browser disconnects or the sandbox hibernates, then reopening the Session reattaches to the durable workflow/stream and resumes the persistent sandbox without silently creating a replacement workspace.

Scenario: GitHub-triggered automation

Given an enabled Automation with an explicit repository allowlist and a matching GitHub trigger, when a verified webhook is received, then exactly one durable Run is created for the delivery, the trigger and permission context are visible, and the Run ends with inspectable evidence or an actionable typed failure.

Scenario: multi-step automation

Given an Automation with multiple steps, when it starts, then the exact definition revision is snapshotted, progress survives restarts, and cancel/retry semantics remain source-correct and idempotent.

Scenario: incomplete production configuration

Given production journey credentials or an allowlist are absent, when readiness or scheduled canaries run, then the state is reported as blocked/unproven, never passed, recovered, or generally green.

Scope and delivery sequence

Phase 0 — establish the durable contract

• Add docs/plans/sessions-automations-runs.md and update the root PLAN.md.
• Record the keep/consolidate/freeze matrix, invariants, dependency graph, rollout plan, and stop conditions.
• Attach every implementation slice as a native child issue.

Phase 1 — trust and additive foundations

1. Make unattended repository allowlists fail closed while preserving explicit * as an intentional override.
2. Make authenticated production canary aggregation distinguish passed, failed, cancelled, and blocked/unproven; never emit recovery for blocked journeys.
3. Add explicit product exposure gates so Verified Build, harness UI, GTM, and disabled generic workflow catalog do not leak into the default product path.
4. Define additive Automation contracts/adapters over background agents and loops.
5. Extract/reuse a normalized Run read contract from Account Coordinator patterns, fixing skipped/unknown/in-flight status gaps.

Phase 2 — Runs before editors

6. Ship a unified Runs API/list with repository, automation, trigger, and attention filters; retain source-specific detail links initially.
7. Ship a normalized Run detail shell that composes existing background-run and loop-run evidence/control panels.

Runs precede editor rehoming because users need a trustworthy place to observe test executions before the new creation flow is promoted.

Phase 3 — one Automation product

8. Ship a unified read-only Automations list.
9. Rehome the existing background-agent creator/editor as the default single-step Automation flow.
10. Rehome the existing loop builder as the advanced multi-step Automation flow.

Phase 4 — remove product duplication

11. Reduce workspace/repository navigation to Sessions, Automations, Runs, and Settings.
12. Regroup Settings, rename interactive chat Agents to Chat roles, and hide experimental authoring from normal users.
13. Align landing/onboarding copy to Connect GitHub -> start Session -> create Automation -> inspect Run.

Phase 5 — runtime convergence after parity

14. Characterize and extract shared step definition, permissions, verification, output, context, and result contracts from the two existing executors.
15. Time-box a migration spike for canonical automation/run storage only after adapters round-trip all existing records and evidence without loss.

Keep, consolidate, and freeze

Keep and harden

• Session/chat durability and stream reattachment
• Persistent sandbox hibernation/resume
• Git diff/commit/PR controls
• GitHub App webhook verification and delivery idempotency
• Background-agent dispatcher/executor and loop step executor
• Trigger conditions, permissions, checks, outputs, costs, events, cancellation, retry, and watchdogs
• Repository/tool connections and runtime evidence

Consolidate behind the new product contract

• Background agents + loops -> Automations
• Background-agent runs + loop runs -> Runs
• Repo Project/Agents/Loops entry points -> repository-filtered Automations
• Activity/recent-run lists -> repository-filtered Runs
• Separate prerequisites/readiness -> one Automation readiness contract

Freeze and preserve

• Verified Build and harness product UI
• Generic workflow catalog
• GTM pages/APIs
• Chief of Staff branding
• Custom managed-runtime profile authoring
• New graph-builder features and new sandbox providers
• Leaderboard/learnings expansion

Freezing means removing default discovery or creation paths behind an explicit product exposure gate. Existing records, diagnostic access, and source code are preserved.

Explicit non-goals

• No big-bang table merge.
• No deletion of definitions, runs, or evidence.
• No executor rewrite before characterization tests.
• No attempt to finish Verified Build, harness, GTM, generic catalog, or managed-runtime profile authoring.
• No new sandbox provider.
• No replacement for GitHub's general PR, issue, action, or secrets administration.
• No claim of production proof from code/tests alone.

Tests to add first

Each child issue must name its protected path and start with the smallest failing unit, contract, route, workflow, or browser test. Cross-epic golden journeys are:

• A Session survives refresh, hibernation, and resume and produces a branch/PR.
• A GitHub PR webhook starts one single-step review Automation exactly once and the Run shows trigger, permissions, sandbox, checks, and output.
• A GitHub issue webhook starts an implementation Automation and produces a tested PR.
• A multi-step Automation persists its definition snapshot, advances steps, and survives refresh/restart.
• Cancel/retry remain source-correct and idempotent.
• Frozen features are absent from default navigation and chat execution.
• Legacy URLs retain access to existing records during transition.
• Missing allowlists and missing canary credentials are blocked/unproven, never passed.

For every behavior-changing PR: focused red test, red commit, smallest green change, adjacent suites, git diff --check, bun --bun run ci, and authenticated Agent Browser smoke for UI paths.

Observability and user feedback

• Canonical Run summaries carry source-qualified IDs, repository, automation revision, trigger/delivery ID, current step, timestamps, evidence link, typed status, and attention reason.
• Important actions use stable service/action vocabulary and correlation fields such as requestId, sessionId, chatId, workflowRunId, runId, deliveryId, and sandboxName where applicable.
• Status mapping must preserve queued, running, waiting, blocked, succeeded, failed, cancelled, skipped, and unknown; only explicit successful terminal states map to succeeded.
• Secrets, provider tokens, auth cookies, raw prompts, session content, and unredacted artifacts must not enter summaries or logs.
• Partial source failures are visible and do not silently remove the other source's data.
• Product proof and production proof remain separate. PRs state whether evidence is deterministic test, local integration, browser smoke, preview smoke, or production smoke.

Debug recipes and structured event details belong in each child issue because service/action names differ by slice.

Regression harness plan

• Adapter contract tests freeze every source-to-canonical mapping.
• Route tests enforce ownership, source qualification, redaction, sorting, filters, and partial-source isolation.
• Workflow/dispatcher tests enforce trigger idempotency, definition snapshotting, cancel/retry, and allowlist behavior.
• Agent Browser journeys cover the authenticated Sessions -> Automations -> Runs product path after deterministic tests pass.
• Production canary workflows expose passed, failed, cancelled, or blocked_by_configuration separately and alert/recover only on truthful transitions.

Regression risks and concerns

• Agent is already overloaded across interactive chat roles, background definitions, and graph nodes; user-facing migration must not deepen that ambiguity.
• Source IDs are not globally unique; every canonical reference must include its source kind.
• Background and loop status/evidence models are not identical; optional fields and source badges are safer than false parity.
• Existing Account Coordinator normalization maps some unknown/skipped states too optimistically and cannot see chat workflow rows until finish.
• Existing allowlist parsing conflates missing config with explicit wildcard.
• Existing production canary commands return success for blocked configuration, allowing misleading recovery signals.
• Open PRs touching background-agent executor/editor files require file-ownership checks before each slice.

Deploy or migration impact

• Early phases are additive or configuration-policy changes; there is no schema migration.
• Fail-closed allowlists can intentionally disable unattended execution until repository lists are configured; readiness and operator docs must explain the unblock.
• Product exposure gates must default experiments off without removing existing diagnostic/detail access.
• Legacy URLs remain readable until replacement parity is tested.
• Any later schema migration requires an independent spike, Neon preview proof with representative rows, backward-compatible reads, rollback/fix-forward instructions, and explicit operator approval.

Agent execution model

• Each child issue uses its own worktree and branch based on origin/develop.
• Independent trust/foundation issues may run in parallel when file ownership does not overlap.
• Dependent UI/runtime slices start only when their contract dependency is merged or deliberately based on that branch.
• Cheap implementation agents own bounded issues; the coordinating frontier agent owns architecture, contract review, security boundaries, integration review, and final evidence quality.
• One issue maps to one focused PR into develop; no agent merges its own PR without an explicit human command.

Global stop conditions

Stop a slice instead of widening it when:

• it requires destructive migration or deletion;
• a legacy definition cannot round-trip losslessly;
• a shared abstraction changes executor behavior before characterization tests exist;
• a normalized Run omits source-specific evidence or controls;
• unattended execution would be enabled without an explicit repository allowlist;
• authenticated persisted UI state cannot load for the required browser proof;
• an external runtime is needed merely to prove deterministic behavior;
• the slice starts pulling frozen systems back into the core product.

Definition of done

• All native child issues are complete with focused PRs merged into develop.
• Default navigation and onboarding expose Sessions, Automations, Runs, and Settings only.
• Existing single-step and multi-step definitions remain readable/editable and execute through their proven source runtimes.
• GitHub-triggered and scheduled execution fail closed outside explicit repository scope.
• Runs expose honest normalized lifecycle/evidence without hiding source-specific detail.
• Golden authenticated browser journeys pass against a database-backed environment.
• Production journey proof reports only actually executed successful journeys as passed/recovered.
• Any remaining storage convergence work is explicitly deferred with measured evidence, not assumed necessary.