background-agent: issue-bound sandbox orchestration and issue-thread journaling

[gHashTag]

Issue-Bound Sandbox Orchestration

Context

Originally, the goal was: GitHub issue ↔ sandbox container/service orchestration. What was completed:

• ✅ Railway API client (create/delete services, deployments, logs)
• ✅ Railway farm mapping (issue → service_id/account_id in .trinity/railway_farm.json)
• ✅ Background-agent HTTP server with sessions CRUD
• ✅ Partial PostgreSQL layer (sessions table)
• ✅ Compile-clean for Zig 0.15 compatibility (issue feat(fpga): DSLogic U2basic integration #484)

What was NOT completed:

• ❌ No issue-centric orchestration — GitHub issue is not the primary identifier for agent work
• ❌ No GitHub issue comment publisher — agent steps don't write to GitHub issue comments/timeline
• ❌ No tri CLI integration — no link between CLI operations, experience files, and GitHub issues

Problem Statement

Currently:

• Agents create sandbox services via Railway
• Work is tracked in .trinity/experience/ markdown files
• There is no connection between GitHub issue numbers and:
  • sandbox session IDs
  • Railway service IDs
  • Deployment statuses
  • Agent work history

This creates a fragmented workflow where:

1. Issue tracking happens on GitHub (where the issue is)
2. Sandbox lifecycle happens on Railway (where the service is)
3. Work history happens in .trinity/experience/ (where the steps are)
4. No unified timeline connecting these three systems

Requirements

1. Canonical Issue-to-Sandbox Mapping

A module that provides:

pub fn getMapping(allocator: Allocator, issue_number: []const u8) !struct {
    session_id: []const u8,
    railway_service_id: []const u8,
    deployment_id: []const u8,
    experience_file: []const u8,
};

• Reads from .trinity/railway_farm.json
• Returns canonical identifiers for a given issue
• Source of truth for all sandbox operations

2. GitHub Issue Comment Publisher

A module that writes agent step/status to GitHub issue:

pub fn publishComment(allocator: Allocator, issue_number: []const u8, message: []const u8) !void {
    // GitHub REST API call
    // Comments become the live journal of agent work
};

Required event types:

• "sandbox_created" — when issue-linked sandbox is provisioned
• "deployment_started" — when Railway deployment begins
• "deployment_succeeded" — when deployment completes
• "deployment_failed" — when deployment fails
• "step_completed" — when agent finishes a work step
• "build_failed" — when build/test fails

3. Tri CLI Integration

Extend tri CLI to integrate with issue binding:

tri agent link <issue_number>    # Link current session to GitHub issue
tri agent unlink                  # Unlink current session
tri agent step <message>         # Write step to experience + publish to GitHub

When tri agent step is called:

1. Creates .trinity/experience/<timestamp>_<issue_number>.md
2. Updates .trinity/current_issue.json with linked issue
3. Calls GitHub issue comment publisher
4. Returns error if not linked to issue

4. Sandbox Lifecycle Hooks

On issue creation/deletion/close:

• Create: Provisions Railway service, runs initialization
• Deploy: Updates deployment, attaches logs
• Execute: OpenCode sandbox (if needed) runs agent code
• Destroy: Stops service, archives logs

Implementation Notes

• Use Zig 0.15 APIs (per CLAUDE.md migration rules)
• Reference GitHub Issue Events REST API
• Reference Rancher Station deployment semantics
• Keep .trinity/railway_farm.json as source of truth for mappings

Out of Scope

• OpenCode sandbox integration (not part of Trinity stack)
• Real-time status syncing (out of scope for this task)
• Multi-user concurrency (handle in future enhancement)

---

Related: #484 (partial completion), #505 (Zig 0.15 migration)

[gHashTag]

Issue-bound sandbox orchestration implemented in src/background_agent/db/issue_bindings.zig. Journaling via sessions.zig.