feat(go): first slice of full Go port of sumctl (#94)

ATTRIBUTIONS.md

@@ -0,0 +1,63 @@
+# Attributions
+
+I am building sum for myself, to the highest standard I can achieve. I am not trying to grow a user base for it, and I would rather you use the projects below than adopt sum. They shaped this project in concrete ways and deserve the credit. Please explore them, use the ones that fit your work, and support their maintainers.
+
+This page distinguishes conceptual inspiration, direct dependency, adapted code, historical lineage, and integrations still being evaluated. Replacing a dependency later does not erase the credit recorded here. It supplements, and never replaces, the license and source notices carried alongside any copied material.
+
+## Where sum comes from
+
+**[Firstmate](https://github.com/kunchenguid/firstmate)** is the origin of **the agent-distro concept that inspired sum**: an ordinary coding harness, portable instructions/skills/helpers, and one liaison coordinating workers. That shape is sum's lineage, not a claim that Firstmate invented agent orchestration generally. If the idea of one coordinator delegating to disposable workers appeals to you, try Firstmate itself first.
+
+**[Consigliere](https://github.com/douglasjarquin/consigliere)** was the author's own earlier, Firstmate-derived experiment: delegation conventions and the light mafia identity sum still carries came from there. It is respectful lineage, not a story about something that didn't work.
+
+## Terminal and session runtime
+
+**[Herdr](https://github.com/herdrdev/herdr)** ([site](https://herdr.dev/)) is the terminal runtime sum is native to: pane, session, and worktree operations are Herdr's own mechanics, and sum deliberately lets an existing runtime own them instead of reimplementing process/session management.
+
+**[Herdr Mesh](https://github.com/runchr-works/herdr-mesh)** supplied the early, concrete MCP bridge and the small shared pane/agent tool surface that sum's own Mesh builtin now implements natively. That credit stands even after internalizing ownership of the implementation.
+
+**[Unpeel](https://unpeel.com/)** is a conceptual inspiration for **MCP pane/session management** and cross-harness coordination — not a claim that any implementation here was copied from it. Worth exploring if you want a more general take on coordinating multiple harnesses through MCP.
+
+**[Solo](https://soloterm.com/)** ([meta-harness explanation](https://soloterm.com/blog/the-agentic-metaharness)) is where the **meta-harness framing** sum uses comes from, along with wakeups, presets, handoffs, selective context, environment awareness, and visibility as ideas worth having regardless of which terminal you run them in. If you want a polished desktop application built around this idea rather than a small CLI helper, Solo is that product.
+
+**[Delta](https://delta.dev/)** shaped how sum thinks about durable, thread-centered work: keeping the conversation and code context attached to a unit of work, and carrying that through handoff and review.
+
+**[Oh My Pi](https://github.com/can1357/oh-my-pi#09--unapologetically-native-even-on-windows)** is the inspiration behind sum's preference for **builtins and reducing avoidable process boundaries** — running logic in-process instead of shelling out where it is practical to do so. This is inspiration, not a claim of an identical architecture or of matching benchmark results.
+
+## Provider quota and evidence
+
+**[quota-axi](https://github.com/kunchenguid/quota-axi)** shaped how sum thinks about provider evidence: freshness and uncertainty made explicit, compact output, and separating collection from policy. It is also the original dependency and inspiration for the author's independent Go sister project, **[Remainder](https://github.com/douglasjarquin/remainder)**. Sum and Pinchos each consume Remainder independently; neither treats it as a sum builtin. Credit to quota-axi stands on its own, without an unmeasured performance comparison.
+
+## Verification and evidence
+
+**[Atlas verification example](https://github.com/poteto/verification-skill-example/blob/main/.cursor/skills/verify-atlas/SKILL.md)** demonstrates feature-driven, real-user-path verification backed by observable evidence — the pattern sum's own verification skills follow. It is one worked example, not a supplied universal recorder or driver.
+
+**[Cursor pstack skills](https://github.com/cursor/plugins/tree/main/pstack/skills)**, in particular [create-verification-skill](https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/SKILL.md) and [maintain-verification-skill](https://github.com/cursor/plugins/blob/main/pstack/skills/maintain-verification-skill/SKILL.md), shaped how sum creates and maintains project verification contracts and feature maps, and how it selects useful upstream skills at all. Individual imported-source attribution is added here as specific skill imports actually land.
+
+**[before-and-after](https://github.com/vercel-labs/before-and-after)** shaped how sum presents and publishes before/after media in a pull request — the presentation and publication step, distinct from the capture itself. Any adapted material keeps its original notices.
+
+## Code exploration
+
+**[codegraph](https://github.com/colbymchenry/codegraph)** provides the structural code context and worktree-local graph exploration every checkout sum creates gets its own index of. Credit reflects the current pinned-binary, per-checkout-index relationship, not earlier planning language.
+
+## Verification companions
+
+**[MADE](https://github.com/douglasjarquin/made)** is the author's existing, independent candidate-bound verification and review companion. It is a separate project with its own relationship to No Mistakes; sum does not conflate the two.
+
+## Bot deployment
+
+**[Grok Ship](https://github.com/kunchenguid/grok-ship)** and the [native Firstmate/Bot template](https://x.ai/bot/__4FfrkUdvpdMk6-LKg5r) it distributes shaped sum's single user-facing Bot / project-Bot deployment model. Where a successor replaces one of these, the historical reference stays.
+
+**[Grok Ship Steward](https://github.com/douglasjarquin/grok-ship-steward)** inspired square, sum's scoped backup/recovery stewardship companion. Any upstream credit Grok Ship Steward itself carries is retained where its material is adapted.
+
+## Tooling and supporting ecosystem
+
+**[mise](https://mise.jdx.dev/)** underlies sum's tool/version/task setup and its portable verification foundations.
+
+**[herdr-mirror](https://github.com/nikok6/herdr-mirror)** was evaluated as a related remote-visibility reference during remote planning. It is labeled evaluated, not installed: sum does not depend on it.
+
+Beyond the named projects above, sum also rests on the broader Agent Skills convention, Git, and the coding harnesses it launches — none of them sum's own work, all of them worth understanding on their own terms.
+
+## The four you'll see most
+
+If you read nothing else on this page: **Firstmate** shaped the agent-distro concept, **Oh My Pi** shaped the preference for builtins, **Solo** shaped the meta-harness framing, and **Unpeel** shaped MCP pane/session management. Go look at all four.

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Use an isolated development checkout and keep the installation serving live work
 - [ ] Run `MISE_ENABLE_TOOLS=go,python,node python3 .agents/skills/verify/scripts/verify_run.py --base <merge-base>` once for your role and retain its candidate-bound record.
 - [ ] Run `mise run test-live` separately only when a real Herdr smoke test applies and is available; otherwise leave that manual scenario accurately not-run.
 - [ ] Describe acceptance results and evidence paths in the handoff, including failures or manual scenarios not run.
-- [ ] Include contributor attribution when applicable and state deployment or release impact when relevant.
+- [ ] Include contributor attribution when applicable, adding an entry to `ATTRIBUTIONS.md` when new material or inspiration enters, and state deployment or release impact when relevant.
 - [ ] Leave branch-protection and merge actions to their owner; a human reviews and merges changes.
 
 The recommended order is scope and prerequisites, implementation, canonical verification, applicable live verification, review, then human merge.

README.md

@@ -395,4 +395,4 @@ The optional Git bundle preserves the bootstrap commit. To use it instead: `git
 
 ## License and inspiration
 
-MIT. Inspired by Firstmate and Consigliere. Uses [Herdr](https://github.com/herdrdev/herdr), [Herdr Mesh](https://github.com/runchr-works/herdr-mesh), and [quota-axi](https://github.com/kunchenguid/quota-axi) rather than replacing them.
+MIT. sum stands on projects it did not write — Firstmate, Herdr, Oh My Pi, Solo, Unpeel, and others. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md) for the complete credit and what each one shaped.

go/cmd/sumctl-go/error_format_test.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestCompiledEntrypoint_errorJSONMatchesPythonSeparatorsAndEscaping(t *testing.T) {
+	if _, err := exec.LookPath("python3"); err != nil {
+		t.Skip("python3 not on PATH")
+	}
+	repoRoot, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	reference := filepath.Join(repoRoot, "bin", "sumctl")
+	if _, statErr := os.Stat(reference); statErr != nil {
+		t.Skipf("reference bin/sumctl not found: %v", statErr)
+	}
+
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "sumctl-go")
+	build := exec.Command("go", "build", "-trimpath", "-buildvcs=false", "-o", binary, ".")
+	if output, err := build.CombinedOutput(); err != nil {
+		t.Fatalf("go build failed: %v\n%s", err, output)
+	}
+
+	home := t.TempDir()
+	args := []string{"--home", home, "preset", "show", "nope"}
+
+	pythonCombined, _ := exec.Command(reference, args...).CombinedOutput()
+	wantStderr := extractLast(string(pythonCombined))
+
+	goCmd := exec.Command(binary, args...)
+	goCombined, _ := goCmd.CombinedOutput()
+	gotStderr := extractLast(string(goCombined))
+
+	if gotStderr != wantStderr {
+		t.Fatalf("go stderr = %q, want (python reference) %q", gotStderr, wantStderr)
+	}
+	if !strings.HasPrefix(gotStderr, `{"error": `) {
+		t.Fatalf("go stderr does not use Python's default json.dumps separators: %q", gotStderr)
+	}
+}
+
+func extractLast(s string) string {
+	lines := strings.Split(strings.TrimRight(s, "\n"), "\n")
+	return lines[len(lines)-1]
+}

go/cmd/sumctl-go/main.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
@@ -11,6 +10,7 @@ import (
 	"syscall"
 
 	"github.com/douglasjarquin/sum/go/internal/cli"
+	"github.com/douglasjarquin/sum/go/internal/ordjson"
 )
 
 func main() {
@@ -23,9 +23,11 @@ func main() {
 		if errors.As(err, &exitErr) {
 			os.Exit(exitErr.Code)
 		}
-		payload, marshalErr := json.Marshal(map[string]string{"error": err.Error()})
+		errorValue := ordjson.NewObject()
+		errorValue.Set("error", err.Error())
+		payload, marshalErr := ordjson.MarshalCompact(errorValue)
 		if marshalErr != nil {
-			fmt.Fprintln(os.Stderr, `{"error":"sumctl-go failed"}`)
+			fmt.Fprintln(os.Stderr, `{"error": "sumctl-go failed"}`)
 		} else {
 			fmt.Fprintln(os.Stderr, string(payload))
 		}

go/cmd/sumctl-go/main_test.go

@@ -53,7 +53,7 @@ func TestCompiledEntrypointCancellationExitsOnce(t *testing.T) {
 	if exit, ok := err.(*exec.ExitError); !ok || exit.ExitCode() != 1 {
 		t.Fatalf("compiled exit = %v, want status 1", err)
 	}
-	if stdout.Len() != 0 || !strings.Contains(stderr.String(), `"error":"context canceled"`) {
+	if stdout.Len() != 0 || !strings.Contains(stderr.String(), `"error": "context canceled"`) {
 		t.Fatalf("compiled cancellation output stdout=%q stderr=%q", stdout.String(), stderr.String())
 	}
 }

go/internal/cli/doctor_test.go

@@ -0,0 +1,89 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+// Safe against the live installation: doctor is documented "never binds" and
+// this port only reads (tool lookups, a herdr pane-get, file existence
+// checks) — the same observation `./bin/sumctl doctor` already performs here.
+func TestDoctor_matchesThePythonReferenceInThisDevCheckout(t *testing.T) {
+	if _, err := exec.LookPath("python3"); err != nil {
+		t.Skip("python3 not on PATH")
+	}
+	repoRoot, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	reference := filepath.Join(repoRoot, "bin", "sumctl")
+	if _, statErr := os.Stat(reference); statErr != nil {
+		t.Skipf("reference bin/sumctl not found: %v", statErr)
+	}
+	if os.Getenv("HERDR_ENV") != "1" || os.Getenv("HERDR_PANE_ID") == "" {
+		t.Skip("not running inside a live Herdr pane")
+	}
+
+	home := filepath.Join(repoRoot, ".sum")
+	args := []string{"--home", home, "doctor"}
+
+	pythonCmd := exec.Command(reference, args...)
+	want, pythonErr := pythonCmd.Output()
+	pythonExit := 0
+	if pythonErr != nil {
+		if exitErr, ok := pythonErr.(*exec.ExitError); ok {
+			pythonExit = exitErr.ExitCode()
+		} else {
+			t.Fatalf("python reference failed: %v", pythonErr)
+		}
+	}
+
+	var stdout, stderr bytes.Buffer
+	root := NewRoot(reference, &stdout, &stderr)
+	root.SetArgs(args)
+	goExit := 0
+	if err := root.ExecuteContext(context.Background()); err != nil {
+		if exitErr, ok := err.(*ExitError); ok {
+			goExit = exitErr.Code
+		} else {
+			t.Fatalf("go command failed: %v (stderr=%s)", err, stderr.String())
+		}
+	}
+
+	if stdout.String() != string(want) {
+		t.Fatalf("go output =\n%s\nwant (python reference)\n%s", stdout.String(), want)
+	}
+	if goExit != pythonExit {
+		t.Fatalf("go exit = %d, want (python reference) %d", goExit, pythonExit)
+	}
+}
+
+func TestDoctor_fallsBackToReferenceWithExtraArgs(t *testing.T) {
+	dir := t.TempDir()
+	argsFile := filepath.Join(dir, "args")
+	reference := filepath.Join(dir, "reference.sh")
+	if err := os.WriteFile(reference, []byte("#!/bin/sh\nprintf '%s\\n' \"$@\" > \"$SUM_GO_ARGS_FILE\"\n"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("SUM_GO_ARGS_FILE", argsFile)
+
+	home := filepath.Join(dir, "state")
+	var stdout, stderr bytes.Buffer
+	root := NewRoot(reference, &stdout, &stderr)
+	root.SetArgs([]string{"--home", home, "doctor", "--unexpected"})
+	if err := root.ExecuteContext(context.Background()); err != nil {
+		t.Fatalf("execute: %v (stderr=%s)", err, stderr.String())
+	}
+	got, err := os.ReadFile(argsFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "--home\n" + home + "\ndoctor\n--unexpected\n"
+	if string(got) != want {
+		t.Fatalf("reference argv = %q, want %q", got, want)
+	}
+}

go/internal/cli/graph_config_test.go

@@ -0,0 +1,135 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+func TestGraphConfig_matchesThePythonReferenceAcrossScenarios(t *testing.T) {
+	if _, err := exec.LookPath("python3"); err != nil {
+		t.Skip("python3 not on PATH")
+	}
+	repoRoot, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	reference := filepath.Join(repoRoot, "bin", "sumctl")
+	if _, statErr := os.Stat(reference); statErr != nil {
+		t.Skipf("reference bin/sumctl not found: %v", statErr)
+	}
+
+	installationReleases := filepath.Join(repoRoot, "..", "..", "..", ".local", "releases")
+	pinned := findPinnedCodegraph(t, installationReleases)
+	if pinned == "" {
+		t.Skip("no pinned codegraph release found to exercise the available-tool path")
+	}
+
+	cases := []struct {
+		name   string
+		env    []string
+		args   []string
+		expect string
+	}{
+		{name: "claude snippet", env: []string{"SUM_CODEGRAPH_BIN=" + pinned}, args: []string{"graph", "config", "--harness", "claude"}},
+		{name: "codex snippet", env: []string{"SUM_CODEGRAPH_BIN=" + pinned}, args: []string{"graph", "config", "--harness", "codex"}},
+		{name: "cursor snippet", env: []string{"SUM_CODEGRAPH_BIN=" + pinned}, args: []string{"graph", "config", "--harness", "cursor"}},
+		{name: "opencode snippet", env: []string{"SUM_CODEGRAPH_BIN=" + pinned}, args: []string{"graph", "config", "--harness", "opencode"}},
+		{name: "raw snippet", env: []string{"SUM_CODEGRAPH_BIN=" + pinned}, args: []string{"graph", "config", "--harness", "claude", "--raw"}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			fullArgs := append([]string{"--home", home}, tc.args...)
+
+			pythonCmd := exec.Command(reference, fullArgs...)
+			pythonCmd.Env = append(os.Environ(), tc.env...)
+			want, err := pythonCmd.Output()
+			if err != nil {
+				t.Fatalf("python reference failed: %v", err)
+			}
+
+			for _, kv := range tc.env {
+				parts := splitEnv(kv)
+				t.Setenv(parts[0], parts[1])
+			}
+			var stdout, stderr bytes.Buffer
+			root := NewRoot(reference, &stdout, &stderr)
+			root.SetArgs(fullArgs)
+			if err := root.ExecuteContext(context.Background()); err != nil {
+				t.Fatalf("go command failed: %v (stderr=%s)", err, stderr.String())
+			}
+
+			if stdout.String() != string(want) {
+				t.Fatalf("go output =\n%s\nwant (python reference)\n%s", stdout.String(), want)
+			}
+		})
+	}
+}
+
+func TestGraphConfig_missingToolErrorMatchesPythonReference(t *testing.T) {
+	if _, err := exec.LookPath("python3"); err != nil {
+		t.Skip("python3 not on PATH")
+	}
+	repoRoot, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	reference := filepath.Join(repoRoot, "bin", "sumctl")
+	if _, statErr := os.Stat(reference); statErr != nil {
+		t.Skipf("reference bin/sumctl not found: %v", statErr)
+	}
+
+	home := t.TempDir()
+	args := []string{"--home", home, "graph", "config", "--harness", "claude"}
+
+	pythonCombined, _ := exec.Command(reference, args...).CombinedOutput()
+
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "sumctl-go")
+	build := exec.Command("go", "build", "-trimpath", "-buildvcs=false", "-o", binary, "../../cmd/sumctl-go")
+	build.Dir = "."
+	if output, err := build.CombinedOutput(); err != nil {
+		t.Fatalf("go build failed: %v\n%s", err, output)
+	}
+	goCmd := exec.Command(binary, args...)
+	goCmd.Env = append(os.Environ(), "SUM_PYTHON_HELPER="+reference)
+	goCombined, _ := goCmd.CombinedOutput()
+
+	if string(goCombined) != string(pythonCombined) {
+		t.Fatalf("go combined output = %q, want (python reference) %q", goCombined, pythonCombined)
+	}
+}
+
+func findPinnedCodegraph(t *testing.T, releasesGlobRoot string) string {
+	t.Helper()
+	matches, err := filepath.Glob(filepath.Join(releasesGlobRoot, "*", ".local", "bin", "codegraph"))
+	if err != nil || len(matches) == 0 {
+		return ""
+	}
+	for _, m := range matches {
+		if info, statErr := os.Lstat(m); statErr == nil && info.Mode()&os.ModeSymlink != 0 {
+			if _, resolveErr := filepath.EvalSymlinks(m); resolveErr == nil {
+				return m
+			}
+			continue
+		}
+		if _, statErr := os.Stat(m); statErr == nil {
+			return m
+		}
+	}
+	return ""
+}
+
+func splitEnv(kv string) [2]string {
+	for i := 0; i < len(kv); i++ {
+		if kv[i] == '=' {
+			return [2]string{kv[:i], kv[i+1:]}
+		}
+	}
+	return [2]string{kv, ""}
+}