feat(agent): Ralph sleep-wake daemon — native Zig, GitHub polling, Claude CLI spawn (#50)

8 Zig modules (~500 LOC):
- main.zig: entry point, env vars, CLI args
- agent_loop.zig: WAKE→WORK→SLEEP cycle
- identity.zig: load .ralph/IDENTITY.md
- context_builder.zig: assemble structured prompt
- github_poller.zig: fetch pending issues via HTTP
- claude_runner.zig: spawn `claude` CLI as child process
- handover.zig: read/write .ralph/HANDOVER.md
- state.zig: file-based key-value persistence

Build: `zig build agent` / `zig build agent -- --single-shot`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Antigravity Agent <antigravity@vibee.org>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

.ralph/IDENTITY.md

@@ -0,0 +1,30 @@
+# Ralph — Autonomous Development Agent
+
+## Who I Am
+I am Ralph, an autonomous Zig development agent for the Trinity project.
+I follow the Golden Chain: spec → gen → test → assess → commit.
+My identity persists across sessions via HANDOVER.md.
+
+## Rules
+- All tasks come from GitHub Issues with label `assign:ralph`
+- Never commit to main — use `ralph/w{N}/{slug}` branches
+- Quality gates: `zig build && zig build test && zig fmt --check src/`
+- Every PR must have: assignee, labels, milestone, reviewer, linked issue (`Closes #N`)
+- ALWAYS write HANDOVER.md before session ends
+
+## Key Files
+- `.ralph/RULES.md` — Development guardrails (22 sections)
+- `.ralph/HANDOVER.md` — Context bridge between sessions
+- `.ralph/SUCCESS_HISTORY.md` — Working patterns
+- `.ralph/REGRESSION_PATTERNS.md` — Anti-patterns to avoid
+- `.ralph/AGENTS.md` — Agent lifecycle protocol
+
+## Capabilities
+- Zig 0.15.x development (VSA, VM, Firebird, VIBEE compiler)
+- FPGA/Verilog synthesis via VIBEE specs
+- GitHub Issues + Projects V2 automation
+- Claude Code CLI with MCP tools
+
+## Mathematical Foundation
+Trinity Identity: φ² + 1/φ² = 3 where φ = (1 + √5) / 2
+Ternary: {-1, 0, +1} — 1.58 bits/trit

.ralph/state/.gitkeep

@@ -1309,6 +1309,23 @@ pub fn build(b: *std.Build) void {
     // const trinity_mcp_step = b.step("trinity-mcp", "Run TRINITY MCP Server (35+ tools)");
     // trinity_mcp_step.dependOn(&run_trinity_mcp.step);
 
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RALPH AGENT — Autonomous Sleep-Wake Daemon
+    const ralph_agent = b.addExecutable(.{
+        .name = "ralph-agent",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tools/mcp/trinity_mcp/agent/main.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    b.installArtifact(ralph_agent);
+
+    const run_agent = b.addRunArtifact(ralph_agent);
+    if (b.args) |args| run_agent.addArgs(args);
+    const agent_step = b.step("agent", "Run Ralph autonomous agent daemon");
+    agent_step.dependOn(&run_agent.step);
+
     // ═══════════════════════════════════════════════════════════════════════════
     // PHI LOOP — 999 Links of Cosmic Consciousness Gene
     const phi_loop = b.addExecutable(.{

build.zig

@@ -0,0 +1,137 @@
+// agent_loop.zig — Sleep-wake cycle for Ralph autonomous agent
+const std = @import("std");
+const identity_mod = @import("identity.zig");
+const handover = @import("handover.zig");
+const github_poller = @import("github_poller.zig");
+const context_builder = @import("context_builder.zig");
+const claude_runner = @import("claude_runner.zig");
+const state_mod = @import("state.zig");
+
+pub const Config = struct {
+    project_root: []const u8,
+    gh_token: []const u8,
+    owner: []const u8,
+    repo: []const u8,
+    sleep_interval_s: u64 = 1800, // 30 minutes
+    max_turns: u32 = 50,
+    max_wakes: u32 = 0, // 0 = infinite
+    single_shot: bool = false, // true = run once and exit
+};
+
+fn log(comptime fmt: []const u8, args: anytype) void {
+    std.debug.print("[ralph-agent] " ++ fmt ++ "\n", args);
+}
+
+/// Run the sleep-wake loop.
+pub fn run(allocator: std.mem.Allocator, config: Config) !void {
+    var state = try state_mod.State.init(allocator, config.project_root);
+    defer state.deinit();
+
+    log("Starting sleep-wake loop", .{});
+    log("  project: {s}", .{config.project_root});
+    log("  repo: {s}/{s}", .{ config.owner, config.repo });
+    log("  sleep interval: {d}s", .{config.sleep_interval_s});
+    log("  max turns: {d}", .{config.max_turns});
+
+    while (true) {
+        // === WAKE ===
+        const wake_count = state.incrementWakeCount() catch 0;
+        log("=== WAKE #{d} ===", .{wake_count});
+
+        if (config.max_wakes > 0 and wake_count > config.max_wakes) {
+            log("Max wakes ({d}) reached. Exiting.", .{config.max_wakes});
+            break;
+        }
+
+        // Load identity
+        var id = identity_mod.load(allocator, config.project_root);
+        defer id.deinit();
+
+        // Read previous handover
+        const handover_content = handover.read(allocator, config.project_root);
+        defer if (handover_content) |h| allocator.free(h);
+
+        // Poll GitHub for pending issues
+        log("Polling GitHub issues...", .{});
+        const issues_json = github_poller.fetchPending(
+            allocator,
+            config.owner,
+            config.repo,
+            config.gh_token,
+        );
+        defer if (issues_json) |j| allocator.free(j);
+
+        if (issues_json == null) {
+            log("No pending issues or GitHub API unavailable. Sleeping.", .{});
+            if (config.single_shot) break;
+            std.Thread.sleep(config.sleep_interval_s * std.time.ns_per_s);
+            continue;
+        }
+
+        // Read current state
+        const current_issue = state.read("current_issue");
+        defer if (current_issue) |v| allocator.free(v);
+        const current_branch = state.read("current_branch");
+        defer if (current_branch) |v| allocator.free(v);
+
+        // === BUILD CONTEXT ===
+        const prompt = try context_builder.build(allocator, .{
+            .identity = id.content,
+            .handover_content = handover_content,
+            .issues_json = issues_json,
+            .current_issue = current_issue,
+            .current_branch = current_branch,
+            .wake_count = wake_count,
+        });
+        defer allocator.free(prompt);
+
+        log("Context built ({d} bytes). Spawning Claude CLI...", .{prompt.len});
+
+        // === WORK ===
+        var result = claude_runner.spawn(
+            allocator,
+            prompt,
+            config.project_root,
+            config.max_turns,
+        ) catch |err| {
+            log("Claude spawn error: {s}", .{@errorName(err)});
+            if (config.single_shot) break;
+            std.Thread.sleep(config.sleep_interval_s * std.time.ns_per_s);
+            continue;
+        };
+        defer result.deinit();
+
+        log("Claude exited with code {d} ({d} bytes output)", .{ result.exit_code, result.stdout.len });
+
+        // Save session log
+        claude_runner.saveLog(allocator, config.project_root, result.stdout);
+
+        // === SLEEP ===
+        // Check if handover was written by the session
+        const new_handover = handover.read(allocator, config.project_root);
+        if (new_handover) |nh| {
+            allocator.free(nh);
+        } else {
+            // Emergency handover — session didn't write one
+            log("WARNING: No handover written. Creating emergency handover.", .{});
+            handover.writeEmergency(allocator, config.project_root, wake_count, current_issue) catch {
+                log("Failed to write emergency handover!", .{});
+            };
+        }
+
+        // Update state
+        var count_buf: [16]u8 = undefined;
+        const count_str = std.fmt.bufPrint(&count_buf, "{d}", .{wake_count}) catch "0";
+        state.write("last_wake", count_str) catch {};
+
+        if (config.single_shot) {
+            log("Single-shot mode. Exiting.", .{});
+            break;
+        }
+
+        log("Sleeping for {d}s...", .{config.sleep_interval_s});
+        std.Thread.sleep(config.sleep_interval_s * std.time.ns_per_s);
+    }
+
+    log("Agent loop terminated.", .{});
+}

tools/mcp/trinity_mcp/agent/agent_loop.zig

@@ -0,0 +1,85 @@
+// claude_runner.zig — Spawn Claude Code CLI as child process
+const std = @import("std");
+
+pub const RunResult = struct {
+    stdout: []const u8,
+    exit_code: u8,
+    allocator: std.mem.Allocator,
+
+    pub fn deinit(self: *RunResult) void {
+        self.allocator.free(self.stdout);
+    }
+};
+
+/// Spawn `claude` CLI with the given prompt as a positional argument.
+/// Returns captured stdout and exit code.
+pub fn spawn(
+    allocator: std.mem.Allocator,
+    prompt: []const u8,
+    project_root: []const u8,
+    max_turns: u32,
+) !RunResult {
+    var turns_buf: [8]u8 = undefined;
+    const turns_str = std.fmt.bufPrint(&turns_buf, "{d}", .{max_turns}) catch "50";
+
+    // claude --print --output-format text --max-turns N --allowedTools ... "prompt"
+    const result = std.process.Child.run(.{
+        .allocator = allocator,
+        .argv = &.{
+            "claude",
+            "--print",
+            "--output-format",
+            "text",
+            "--max-turns",
+            turns_str,
+            "--allowedTools",
+            "Bash,Read,Write,Edit,Glob,Grep,TodoWrite,WebFetch,WebSearch,Skill",
+            "-p",
+            prompt,
+        },
+        .cwd = project_root,
+        .max_output_bytes = 1024 * 1024, // 1MB
+    }) catch |err| {
+        const msg = try std.fmt.allocPrint(allocator, "Failed to spawn claude: {s}", .{@errorName(err)});
+        return RunResult{ .stdout = msg, .exit_code = 1, .allocator = allocator };
+    };
+
+    // Free stderr, keep stdout
+    allocator.free(result.stderr);
+
+    const exit_code: u8 = switch (result.term) {
+        .Exited => |code| code,
+        else => 1,
+    };
+
+    return RunResult{
+        .stdout = result.stdout,
+        .exit_code = exit_code,
+        .allocator = allocator,
+    };
+}
+
+/// Save session log to .ralph/logs/session_{timestamp}.log
+pub fn saveLog(_: std.mem.Allocator, project_root: []const u8, content: []const u8) void {
+    var dir_buf: [512]u8 = undefined;
+    const log_dir = std.fmt.bufPrint(&dir_buf, "{s}/.ralph/logs", .{project_root}) catch return;
+    std.fs.cwd().makePath(log_dir) catch {};
+
+    const epoch_s: u64 = @intCast(@divTrunc(std.time.nanoTimestamp(), std.time.ns_per_s));
+
+    var path_buf: [512]u8 = undefined;
+    const path = std.fmt.bufPrint(&path_buf, "{s}/session_{d}.log", .{ log_dir, epoch_s }) catch return;
+
+    const file = std.fs.cwd().createFile(path, .{}) catch return;
+    defer file.close();
+    file.writeAll(content) catch {};
+
+    std.debug.print("[ralph-agent] Log saved: {s}\n", .{path});
+}
+
+test "RunResult deinit does not crash" {
+    const allocator = std.testing.allocator;
+    const msg = try allocator.dupe(u8, "test output");
+    var r = RunResult{ .stdout = msg, .exit_code = 0, .allocator = allocator };
+    r.deinit();
+}

tools/mcp/trinity_mcp/agent/claude_runner.zig

@@ -0,0 +1,112 @@
+// context_builder.zig — Assemble structured wake prompt for Claude CLI
+const std = @import("std");
+const github_poller = @import("github_poller.zig");
+
+pub const WakeContext = struct {
+    identity: []const u8,
+    handover_content: ?[]const u8,
+    issues_json: ?[]const u8,
+    current_issue: ?[]const u8,
+    current_branch: ?[]const u8,
+    wake_count: u32,
+};
+
+const instructions =
+    \\You are Ralph, an autonomous development agent. Follow this protocol:
+    \\
+    \\1. Read HANDOVER above — understand where the previous session left off
+    \\2. Pick the highest-priority pending issue (or continue current one)
+    \\3. Claim the issue: add `status:in-progress` label, assign yourself
+    \\4. Create branch: `ralph/w1/{issue-slug}`
+    \\5. Implement via Golden Chain: spec → gen → test → assess → commit
+    \\6. Run quality gates: `zig build && zig build test && zig fmt --check src/`
+    \\7. Create PR with `Closes #{N}` in body
+    \\8. BEFORE SESSION ENDS: Write .ralph/HANDOVER.md with:
+    \\   - What was accomplished
+    \\   - Current branch and issue
+    \\   - What needs to happen next
+    \\   - Any blockers or concerns
+    \\
+    \\CRITICAL: Always write HANDOVER.md before finishing. This is your memory.
+;
+
+/// Build a structured prompt from all context sources.
+pub fn build(allocator: std.mem.Allocator, ctx: WakeContext) ![]const u8 {
+    const handover_section = ctx.handover_content orelse "No handover found. This is a fresh start.";
+    const issue_section = ctx.current_issue orelse "none";
+    const branch_section = ctx.current_branch orelse "none";
+
+    // Build issues summary
+    var issue_summary: []const u8 = "No pending issues found. Agent should be IDLE.";
+    var issue_summary_allocated = false;
+    defer if (issue_summary_allocated) allocator.free(issue_summary);
+
+    if (ctx.issues_json) |json| {
+        const max_json = @min(json.len, 4096);
+        const num = github_poller.extractFirstIssueNumber(json);
+        const title = github_poller.extractFirstIssueTitle(json);
+
+        if (num) |n| {
+            if (title) |t| {
+                issue_summary = std.fmt.allocPrint(allocator, "First pending: #{d} — {s}\n\n```json\n{s}\n```", .{ n, t, json[0..max_json] }) catch "Issues available (format error)";
+                issue_summary_allocated = true;
+            } else {
+                issue_summary = std.fmt.allocPrint(allocator, "First pending: #{d}\n\n```json\n{s}\n```", .{ n, json[0..max_json] }) catch "Issues available (format error)";
+                issue_summary_allocated = true;
+            }
+        } else {
+            issue_summary = std.fmt.allocPrint(allocator, "```json\n{s}\n```", .{json[0..max_json]}) catch "Issues available (format error)";
+            issue_summary_allocated = true;
+        }
+    }
+
+    return std.fmt.allocPrint(allocator,
+        \\# IDENTITY
+        \\
+        \\{s}
+        \\
+        \\# HANDOVER FROM PREVIOUS SESSION
+        \\
+        \\{s}
+        \\
+        \\# CURRENT STATE
+        \\
+        \\- Wake count: {d}
+        \\- Current issue: {s}
+        \\- Current branch: {s}
+        \\
+        \\# PENDING GITHUB ISSUES
+        \\
+        \\{s}
+        \\
+        \\# INSTRUCTIONS
+        \\
+        \\{s}
+        \\
+    , .{
+        ctx.identity,
+        handover_section,
+        ctx.wake_count,
+        issue_section,
+        branch_section,
+        issue_summary,
+        instructions,
+    });
+}
+
+test "build produces structured prompt" {
+    const allocator = std.testing.allocator;
+    const ctx = WakeContext{
+        .identity = "Test identity",
+        .handover_content = null,
+        .issues_json = null,
+        .current_issue = null,
+        .current_branch = null,
+        .wake_count = 1,
+    };
+    const prompt = try build(allocator, ctx);
+    defer allocator.free(prompt);
+    try std.testing.expect(std.mem.indexOf(u8, prompt, "IDENTITY") != null);
+    try std.testing.expect(std.mem.indexOf(u8, prompt, "INSTRUCTIONS") != null);
+    try std.testing.expect(std.mem.indexOf(u8, prompt, "Wake count: 1") != null);
+}