[FEATURE] Add durable agent run log for GitHub issue workflow

[Joncallim]

Problem Statement

FORGE's GitHub-native workflow will involve issue validation, command comments, dispatch requests, agent runs, branches, PRs, checkpoints, and reviews. If these events are only visible in transient GitHub Actions logs or chat sessions, the workflow will be hard to audit and resume.

FORGE needs a durable agent run log that links an issue to the requested agent, command, generated branch, dispatch state, PR, and final outcome.

Parent Epic: #141

Desired Outcome

Every accepted agent request creates or updates a durable run record. The record should survive chat/session loss and be easy for humans and future FORGE UI components to read.

The first version can be a repository-local JSONL or markdown-backed log. It does not need a database.

User Story

As a FORGE user,
I want every agent request and result to be recorded,
So that I can see what happened, resume interrupted work, and trace PRs back to issues and commands.

Requirements

• Define a durable run record schema.
• Store run records in a simple repository-visible location for MVP, for example:
  • .forge/runs/agent-runs.jsonl, or
  • .forge/runs/<issue-number>/<run-id>.json
• Each run record should include:
  • run id
  • issue number
  • issue title
  • requested agent/runtime
  • requested action
  • requester
  • source comment id, where available
  • created timestamp
  • current status
  • branch name, where available
  • PR number, where available
  • blocked reason, where applicable
  • validation summary
• Append or update run status as the workflow progresses.
• Provide helper functions for creating and updating run records.
• Ensure the command router and dispatcher can write to the run log.
• Document how the run log relates to checkpoints from issue [FEATURE] Add cross-agent continuation and checkpointing #32.
• Avoid storing secrets, credentials, full prompts with sensitive content, or unnecessary chat transcripts.

Acceptance Criteria

• A run record schema is documented.
• Accepted agent commands create a run record.
• Dispatch state changes can update or append to the run record.
• Run records link issue number, agent/runtime, action, requester, and status.
• Branch and PR numbers can be added when available.
• Blocked runs include a clear blocked reason.
• Run log location is documented.
• Run log avoids secrets and unnecessary full chat transcripts.
• Tests or fixtures cover run record creation and update.

Out of Scope

• Do not build a database-backed run history in this issue.
• Do not build a visual dashboard.
• Do not store full model conversations by default.
• Do not merge this with the cross-agent checkpointing issue; link to it cleanly instead.

Implementation Scope

Medium - multiple files or components

Technical Notes

Suggested JSONL shape:

{
  "runId": "issue-123-20260703-001",
  "issueNumber": 123,
  "issueTitle": "[FEATURE] Example",
  "runtime": "claude-code",
  "action": "implement",
  "requestedBy": "Joncallim",
  "source": {
    "type": "issue_comment",
    "commentId": 123456789
  },
  "status": "requested",
  "branchName": "agent/issue-123-example",
  "prNumber": null,
  "blockedReason": null,
  "createdAt": "2026-07-03T00:00:00Z",
  "updatedAt": "2026-07-03T00:00:00Z"
}

Suggested status values:

requested
accepted
running
blocked
pr-opened
completed
failed
cancelled

Suggested helper API:

createRunRecord(input: CreateRunRecordInput): AgentRunRecord
appendRunEvent(runId: string, event: AgentRunEvent): void
findLatestRunForIssue(issueNumber: number): AgentRunRecord | null
linkPullRequest(runId: string, prNumber: number): void

Storage options:

1. JSONL file: simple append-only audit log, easy to inspect, harder to update in concurrent workflows.
2. One JSON file per run: easier to update, more files.
3. Markdown summary plus JSON details: more human-readable, slightly more maintenance.

Recommended MVP: one JSON file per run under .forge/runs/<issue-number>/<run-id>.json, plus a future index if needed.

GitHub Actions permission note:

If workflows commit run records back to the repository, they need contents: write. If run records are only posted as issue comments or artifacts, they may not. Keep permissions minimal per workflow.

Reference:
https://docs.github.com/en/actions/tutorials/authenticate-with-github_token

[Joncallim]

Architecture note (pre-implementation) — from the Epic #141 architecture pass. Refines this issue against verified repo facts; original text unchanged.

Corrections before implementing #146:

1. Storage path must change — .forge/ is git-ignored. .gitignore ignores .forge/ (grouped with .env secrets and local-memory/), so run records under .forge/runs/… would never be committed — defeating the "durable, repository-visible" goal. Use a new tracked top-level directory forge-runs/, one JSON file per run (forge-runs/<issue>/<runId>.json). A .gitignore negation inside .forge/ is rejected: it's secrets-adjacent, and git can't re-include a path beneath an excluded directory anyway.
2. Who commits (least privilege). Only the manually-triggered dispatch job holds contents: write and commits run records — event-driven routers never do. Use a shared per-issue concurrency group across every committer and commit-once-then-retry-push (never git commit inside the retry loop).
3. Deterministic runId = issue-<n>-<GITHUB_RUN_ID>-<GITHUB_RUN_ATTEMPT> — no wall-clock, no random (those produce duplicate records on re-run). Enforce with a Zod .regex(); the record schema is .strict() so field drift fails tests instead of crashing a reader.
4. Link, don't merge, [FEATURE] Add cross-agent continuation and checkpointing #32. Carry checkpointIssueRef: 32 and keep cross-agent checkpointing ([FEATURE] Add cross-agent continuation and checkpointing #32, ADR 0004) a separate concern. No secrets, tokens, or full transcripts in records.

The frozen AgentRunRecord Zod schema is a PR-0 deliverable; this storage decision is recorded in ADR 0008.