Skip to content

AXI-137: Separate run provenance and issue lifecycle #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Codename-11 merged 1 commit into from
Jul 20, 2026
Merged

AXI-137: Separate run provenance and issue lifecycle #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,18 @@ The dashboard's **What's New** rail reads this file at request time
entries. Keep entries terse — one line per item under each version
date, grouped by `Added` / `Changed` / `Fixed` / `Removed`.

## [2026-07-20] — v0.29.3 · Honest delivery provenance

### Changed

- **Workstream cards report recorded execution facts.** Agent Profile configuration, MCP or webhook transport, managed runtime execution, run state, and delivery-session state remain separate instead of inheriting a configured runtime onto direct MCP work.
- **Connection presence describes reachability, not work in progress.** Delivery badges say MCP connected, runtime reachable, or connection online and explain that presence never substitutes for an active AgentRun.

### Fixed

- **Explicit MCP execution advances issue lifecycle.** Opening an `EXECUTE` run applies the workspace's configured In Progress status, and successful completion applies In Review, with tenant-scoped audit and activity evidence for each server-side transition.
- **New workspaces receive complete lifecycle targets.** In Progress, In Review, and Done statuses are selected when a workspace is created, while non-execution modes remain status-neutral and Ready to Close continues to ignore transport presence.

## [2026-07-20] — v0.29.2 · Reliable runtime handoff

### Changed
Expand Down
22 changes: 22 additions & 0 deletions DEVLOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,28 @@

> Append-only session log. Read at session start. Update at session end.

## 2026-07-20 — AXI-137 delivery provenance and lifecycle truth

Separated Agent Profile configuration from output-producing run provenance in
the issue Workstream. Direct Codex Desktop and other MCP activity now reports
its MCP connection without claiming the profile's configured managed runtime;
managed runtime execution is shown only when the run records both that
connection and an external run id. Delivery connection badges now describe
transport reachability and explicitly avoid presenting connection presence as
run state.

Opening an explicit MCP `EXECUTE` run now applies the workspace's configured
In Progress status, and successful completion continues to apply In Review.
Both server-owned transitions write tenant-scoped issue audit and activity
evidence. Research, review, and discussion modes remain status-neutral. New
workspaces select their initial In Progress, In Review, and Done lifecycle
targets during creation; existing workspaces retain their settings until an
operator deliberately configures them.

Added focused unit and integration coverage for honest provenance, lifecycle
auditing, non-execution modes, and the invariant that an active MCP connection
or Delivery session does not block Ready to Close without an active run.

## 2026-07-20 — AXI-136 fast local verification and release workflow

Replaced the Unix-only local CI shell chain with a cross-platform TypeScript
Expand Down
13 changes: 13 additions & 0 deletions docs/engineering/work-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,12 @@ client rather than guessed as Codex Desktop or CLI. A runtime is shown only
when an output-producing `AgentRun` carries both a runtime connection and an
external run id. Direct MCP or UI work does not imply runtime execution.

Connection presence is endpoint reachability, not execution state. “MCP
connected,” “runtime reachable,” and similar badges can remain current after a
run has completed because the client is still connected. Ready to Close and
stale-run recovery use `AgentRun` lifecycle records, never connection presence
or an `IN_REVIEW` Delivery session, to decide whether work is still active.

## Project branch contract

Branch topology is project configuration, not an Axiom-wide constant. Every
Expand Down Expand Up @@ -109,6 +115,13 @@ Claimed → In progress → PR open → In review → Ready to merge → Merged
ownership lease. A stale session remains a lease and raises a shared action
request; it must be resumed or abandoned before replacement work starts.

For direct MCP work, clients open an explicit run before implementation.
Opening an `EXECUTE` run moves a Backlog or Todo issue to the workspace's
configured In Progress status; successfully completing it moves the issue to
the configured In Review status. Research, review, and discussion runs do not
change issue status. These are server-side, audited transitions so clients do
not need to race a separate status mutation.

Release, deploy, and verification transitions require workspace admin authority.
Feature work may run in parallel, but merges and production delivery are
serialized.
Expand Down
9 changes: 7 additions & 2 deletions docs/guide/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,11 @@ Workspace-scoped statuses, each in a fixed category (`BACKLOG`, `TODO`,
- Reorder within a category.
- Set the workspace default (used for fresh issues with no explicit
status).
- Configure agent lifecycle targets for **In Progress**, **In Review**, and
**Done**. New workspaces select the first status in each matching category.
An explicit MCP `EXECUTE` run applies In Progress when it opens and In Review
when it completes; research, review, and discussion runs never move issue
status automatically.

### Templates

Expand Down Expand Up @@ -144,7 +149,7 @@ content between instances as portable JSON.
sprints, agents, and issues (with assignees, labels, and relations) plus
comments. Infra rows — API keys, webhooks, the audit log, and attachment
bytes — are excluded.
- **Import** loads a snapshot into the current workspace. It is *additive*:
- **Import** loads a snapshot into the current workspace. It is _additive_:
config rows are matched by natural key and reused, issues are created
fresh with new numbers, relations and comments are rewired onto them, and
unknown authors fall back to you. Nothing is deleted.
Expand Down Expand Up @@ -221,7 +226,7 @@ See [Automation → API keys](/automation/api-keys.html).

URL: `/settings/auth`. **Instance-admin only** — gated on the operator
whose email matches `ADMIN_EMAIL`, since sign-in providers are global to
the whole self-hosted instance (auth is per *user*, not per workspace).
the whole self-hosted instance (auth is per _user_, not per workspace).

Configure how people sign in, without a redeploy:

Expand Down
16 changes: 8 additions & 8 deletions docs/reference/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -498,14 +498,14 @@ heartbeat returns a missing-row error.
`recordUsage` requires `WRITE_ISSUES` and an agent-linked key whose
`linkedAgentId` matches the run's `agentId`. `list` requires `READ_ISSUES`.

| Tool | Summary |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Open (or resume) a tracked run on an issue **you** are working — `{ issueId, summary?, mode? }`. Requires an agent-linked key; the run belongs to the key's `linkedAgentId`. Resumes an existing ACTIVE/WAITING run for the `(issue, agent)` pair instead of stacking a duplicate, and stamps a STARTED event so it shows in Mission Control. Lets an agent (e.g. a local CLI session) proactively self-report work rather than only getting a run as a dispatch side-effect. Issue-anchored; drive it afterward with `recordUsage` / `setWaiting` / `complete`. Scope `WRITE_ISSUES`. |
| `recordUsage` | Update token + cost columns on an `AgentRun`. `{ runId, tokensIn?, tokensOut?, tokensCached?, costUsd? }`. Idempotent — latest call replaces (cumulative as reported by the agent). |
| `complete` | Close an active/waiting run. `{ runId, summary, producedArtifactIds?, verificationResult?, followUps?, confidence?, verdict? }`. Requires an agent-linked key matching the run. Execute enforces issue artifact/checklist gates; Research requires `confidence`; Review requires `verdict`; Discuss is reply-only. Stores `completionMeta` with the Forge run contract version. |
| `setWaiting` / `resumeWork` | Mark a run blocked on the operator, or resume it. Requires an agent-linked key matching the run. |
| `list` | List `AgentRun` rows for "my recent history" introspection. `{ agentId?, issueId?, status?, limit? = 50, before? }` → newest-first by `startedAt`. Each row includes scalars (status, currentStep, startedAt, finishedAt, lastEventAt, tokensIn, tokensOut, tokensCached, costUsd) plus `issue { id, number, title, workspace: { key } }` and `agent { id, profileKey }`. |
| `kick` | Operator-driven nudge for a stalled run. `{ runId }`. Re-fires the dispatch webhook for the underlying issue without changing assignment or `controlState`. Only kicks an `ACTIVE` run that's been quiet 5+ minutes; younger runs return `{ ok: true, kicked: false }`. Records `AGENT_RUN_KICKED`. Scope: `WRITE_ISSUES`. |
| Tool | Summary |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Open (or resume) a tracked run on an issue **you** are working — `{ issueId, summary?, mode? }`. Requires an agent-linked key; the run belongs to the key's `linkedAgentId`. Resumes an existing ACTIVE/WAITING run for the `(issue, agent)` pair instead of stacking a duplicate, and stamps a STARTED event so it shows in Mission Control. An `EXECUTE` run also applies the workspace's configured In Progress status with audit evidence; `RESEARCH`, `REVIEW`, and `DISCUSS` do not change issue status. Lets an agent (e.g. a local CLI session) proactively self-report work rather than only getting a run as a dispatch side-effect. Issue-anchored; drive it afterward with `recordUsage` / `setWaiting` / `complete`. Scope `WRITE_ISSUES`. |
| `recordUsage` | Update token + cost columns on an `AgentRun`. `{ runId, tokensIn?, tokensOut?, tokensCached?, costUsd? }`. Idempotent — latest call replaces (cumulative as reported by the agent). |
| `complete` | Close an active/waiting run. `{ runId, summary, producedArtifactIds?, verificationResult?, followUps?, confidence?, verdict? }`. Requires an agent-linked key matching the run. Execute enforces issue artifact/checklist gates and applies the configured In Review status after successful completion with audit evidence; Research requires `confidence`; Review requires `verdict`; Discuss is reply-only. Stores `completionMeta` with the Forge run contract version. |
| `setWaiting` / `resumeWork` | Mark a run blocked on the operator, or resume it. Requires an agent-linked key matching the run. |
| `list` | List `AgentRun` rows for "my recent history" introspection. `{ agentId?, issueId?, status?, limit? = 50, before? }` → newest-first by `startedAt`. Each row includes scalars (status, currentStep, startedAt, finishedAt, lastEventAt, tokensIn, tokensOut, tokensCached, costUsd) plus `issue { id, number, title, workspace: { key } }` and `agent { id, profileKey }`. |
| `kick` | Operator-driven nudge for a stalled run. `{ runId }`. Re-fires the dispatch webhook for the underlying issue without changing assignment or `controlState`. Only kicks an `ACTIVE` run that's been quiet 5+ minutes; younger runs return `{ ok: true, kicked: false }`. Records `AGENT_RUN_KICKED`. Scope: `WRITE_ISSUES`. |

`costUsd` is taken verbatim from the agent for v1; a server-side
rate table per model is a future enhancement.
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "forge",
"version": "0.29.2",
"version": "0.29.3",
"private": true,
"description": "Forge — a fast, minimalist, keyboard-driven project management platform with pluggable agents.",
"license": "MIT",
Expand Down
Loading
Loading