@pi-in-go/pigpen-extension-equivalence 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Kinsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Extension equivalence harness
+
+A Go extension Package that proves a Go port of a Pi extension behaves like the
+TypeScript original. It is what the
+[`pig-extension-porter`](../../piglets/pig-extension-porter/README.md) Piglet calls,
+and it works on its own: `pig install ./components/extension-equivalence`.
+
+It provides four model tools and one command-line program (`pigeq`, the same
+code):
+
+| Tool / command | Use |
+|---|---|
+| `equivalence_gaps` / `pigeq gaps` | Static: list the Pi APIs the TypeScript uses that the Go SDK lacks (`ctx.newSession({ setup })`, `pi.on("cache_warming_decision")`, ...). A missing API cannot show up in any scenario, because the Go lane cannot call it, so only a static check sees it. Rows come from PiG's `docs/extension-sdk-surface.md`; a snapshot of its non-implemented rows and its `pi.*` rows (PiG 0.4.1, Pi 1.0.1) is embedded, and `--surface` reads a fresh copy. A `pi.<member>` the table has no row for is an API that PiG predates (`pi.registerToolRenderer` before PiG 0.4.1) and is reported missing. `--ts` takes a file (read with the local modules it imports or re-exports) or a multi-file extension's directory; on a table where `pi.events` is missing for Go (PiG 0.3.x), the bus reached through an alias, destructuring or an index is reported too; `--accept-gaps` lists owner-approved exclusions. |
+| `equivalence_run` mode `run` / `pigeq run` | Live: the original under **Pi**, the original under **PiG's Node runtime**, and the Go port under **PiG**, with the same scripted scenario. The port passes when its trace equals Pi's. The PiG-Node lane proves the trace is host-neutral. |
+| mode `record` / `pigeq record` | Write golden traces from Pi (and refuse a scenario on which Pi and PiG's Node lane disagree). Commit them. |
+| mode `check` / `pigeq check` | Compare only the Go port with the golden traces. Needs no Pi installation, so it can run wherever `pig` does. |
+| `pigeq check --builtin --pig <Binary>` | Prove a built Piglet Binary against the goldens: the port is compiled in, so no extension directory is loaded with `-e`. Not available for `mutate`. |
+| `equivalence_run` mode `mutate` / `pigeq mutate` | Apply deliberate defects to a copy of the port; every one must make a scenario fail (or, with the SDK directory, the port's own Go tests). `--unit-only` (tool: `unitOnly`) judges by the port's own tests alone, for a port with no scenarios; `--jobs N` runs mutants in parallel; each unit run is bounded by `-timeout=180s`; a mutant is judged only after the unmutated port's tests pass, and only a reported test failure is a kill. |
+| (in `run`, `record`, `check`) | Two pseudo-scenarios: `sdk-gaps` (above) and `exec-coverage`: every command the original or the port starts by a literal name must be declared in some scenario's `commands` and must be a bare name, because an undeclared command runs unshimmed and unrecorded. A command in code no scenario reaches (a development launcher, a deferred feature, an SQL statement handed to a driver's `exec`) is excused by the owner with an `"exec:<name>": "<reason>"` entry in the `--accept-gaps` file; it stays listed with its reason, and a path is never excused. |
+| `equivalence_diff` / `pigeq diff` | First difference between two traces. |
+| `equivalence_twins` / `pigeq twins list\|check` | The twin contract: `list` writes the ledger of upstream test titles per file; `check` requires each title to have a Go `tw(...)` twin or a named `tskip(...)` (for a Go original: a test function of the same name, or one that skips first, directly or through a skip helper, as a named skip), rejects unknown titles and one reason shared by many skips, and prints the `N exact twins, M skipped` line for `PORT.md`. Helpers: the Skill's `references/twin_test.go.txt`. |
+| `pigeq llm --script turns.json [--log F]` | Serves the scenarios' scripted OpenAI-compatible model on a loopback port (prints its base URL; stops when stdin closes) and logs each request as a JSON line. For a port's own end-to-end run, for example an adapter driven by a real client. |
+| `pigeq env`, `pigeq source` | Session setup (CLI only). `env --root DIR --pig PIG --pi PI --source DIR --module EXTDIR` prints an isolated shell environment to source (temporary `HOME`, `PIG_HOME`, agent directories; the real `go` and `node` first on `PATH`; `GOCACHE` and `GOMODCACHE` kept; `PIG_SDK_GO_ROOT` unset) and, with `--pig` and `--module`, writes a `go.work` that resolves PiG's SDK. `source --from PIG-REPO --rev COMMIT --out DIR` exports a PiG revision as a one-commit git checkout for `PIG_SOURCE_ROOT`. |
+
+**Go source** is scanned too: `pigeq gaps --go DIR` (tool: `equivalence_gaps` with `go`) reports
+`MISSING` for an import of a PiG package other than the public SDK and for the process-global
+calls PiG's fuse check rejects (`os.Exit`, `os.Chdir`, `os.Stdout`, `log.Fatal*`, `fmt.Print*`), and
+`PARTIAL` for SDK stand-ins the surface table records. `run` and `check` repeat it on the port
+as the `port-gaps` pseudo-scenario. Test files and `package main` files are not scanned.
+
+**Oracles.** `record` takes exactly one of `--ts` (a TypeScript original, run under Pi: the
+proof of equivalence), `--go-oracle DIR` (an original that is already a Go extension, run
+under PiG) or `--self` (no original exists: the port is recorded as its own regression
+baseline). The golden trace's header names the kind and `check` labels a self-recorded trace
+as a baseline, not equivalence. `run` needs an original.
+
+## Go originals (relocations)
+
+A Go extension moved from another repository has no Pi oracle. Pass `--go-oracle <dir>` (the
+unmodified original, named with its exact package directory when it lives inside a larger
+module) instead of `--ts` and `--pi`:
+
+```sh
+pigeq record --scenarios port/scenarios --golden port/golden --go-oracle <original-dir> --pig $PIGEQ_PIG
+pigeq check  --scenarios port/scenarios --golden port/golden --go extensions/<name> --pig $PIGEQ_PIG
+pigeq run    --scenarios port/scenarios --go-oracle <original-dir> --go extensions/<name> --pig $PIGEQ_PIG
+```
+
+To get a runnable original from a monorepo whose module replaces the SDK by a relative path,
+export it and point that path at the staged SDK:
+
+```sh
+git -C <repo> archive <full-commit> piglets/standard | tar -x -C X
+mkdir -p X/extensions && ln -s "$(pig reload --sdk-path | tail -1)" X/extensions/sdk
+# --go-oracle X/piglets/standard/extensions/<name>
+```
+
+The original runs under PiG as the lane `pig-go-upstream` and is what the relocated code must
+equal; there is no SDK gap scan and no host check (both lanes are the same host). Mark the
+port with `port/relocation.json` so the repository's layout test expects that lane name.
+`ui.custom` overlays and other terminal-only effects are still invisible to the trace.
+
+## How a scenario runs
+
+Each lane starts a real host in RPC mode (`pi --mode rpc` or `pig --mode rpc`) in a
+scratch workspace with a hermetic environment (no inherited HOME, credentials or
+configuration). The scenario is data (see [scenarios](extensions/extension-equivalence/eq/scenario.go)):
+
+- `files`, `setup`: the workspace, including a git repository;
+- `commands`: child processes the extension may start, each `real` (run the real tool
+  and record the call), `canned` (fixed stdout, stderr, exit) or `missing` (not on PATH);
+- `llm`: scripted model turns served by a local OpenAI-compatible server (so tool calls,
+  `tool_call`/`tool_result`/`context` events and turn order are exercised without a model);
+- `agentFiles`: files written under the lane's agent directory before the host starts (an extension's user-level config; `{{server:NAME}}` expanded).
+- `servers`, `env`: fake HTTP upstreams for an extension that calls an API (a search provider, a judge
+  model, a remote agent). Each server has routes (method, exact or prefix path, required query
+  parameters, status, headers, `body` or `json`, `delayMs`, `times`, `drop`) and gets its own loopback
+  port per lane. `{{server:NAME}}` in `env`, `files` and `args` is its base URL, so provider base URLs
+  and fake credentials can point at it. Every request it receives enters the trace (`http`: method,
+  path, query, body decoded, content type and the headers listed in `recordHeaders`; user agents and
+  other runtime-specific headers stay out), and a URL an extension echoes back is normalized to
+  `<server:NAME>`. Verified live: a TypeScript extension under Pi and its Go port under PiG send the
+  same request and produce identical traces, and a port that sends another header fails at the request.
+  Parallel requests arrive in a nondeterministic order. A port whose SSRF guard refuses loopback needs the
+  extension's own allow-list for the fake server's range, written with `agentFiles` (pigpen-websearch: `ssrf.allowRanges` in its `web-search.json`).
+- `env` alone (no servers) switches an opt-in extension on: `"env": {"PIGPEN_WARDEN_ENABLED": "1"}` reaches the host process of every lane, the original under Pi and the port under PiG alike, on top of the hermetic environment (the harness's own variables and the test process's environment do not leak in). `PATH`, `HOME`, `TMPDIR`, `LANG`, `TERM`, `NO_COLOR`, the Go toolchain variables (`GOROOT`, `GOCACHE`, `GOMODCACHE`, `GOPATH`, `GOFLAGS`, `GOPROXY`, `GONOSUMDB`, `GONOSUMCHECK`, `GOSUMDB`, `GOTOOLCHAIN`), `GOWORK`, `GOENV` and every `EQ_*`, `PIG_*`, `PI_*` and `GIT_*` name are the harness's and are rejected. Tested with a fake host that records its environment (`TestScenarioEnvReachesEveryLaneAndKeepsTheHostHermetic`).
+- `steps`: RPC commands, and the answers to the dialogs they raise. Session operations
+  that only an extension command context can start (`new session`, `fork`) go through a
+  small driver extension loaded in every lane (`/eq-new`, `/eq-fork`).
+
+Recorded per step, in arrival order: UI requests (dialogs, notifications, status,
+widgets), exec calls and exits (via PATH shims), requests that reached the model (the
+messages, every tool's full definition, and the extension's part of the system prompt:
+its difference from the same host's baseline prompt without the extension), tool
+executions and results, agent and turn lifecycle, `extension_error`, command responses,
+and the host exit. After the last step a final quiet period (`tailMs`, default 1000 ms)
+records late effects instead of losing them at shutdown. The normalizer removes only values that differ on every run
+(paths, UUIDs, timestamps, host session ids, the bash tool's measured wall time); its rules N1 to N6 are listed in
+[normalize.go](extensions/extension-equivalence/eq/normalize.go) and versioned, and a
+golden trace recorded under another version is refused.
+
+## Limits
+
+- The trace holds what an extension can influence through RPC. Terminal cells and
+  TUI-only behavior (custom components, overlays) are not compared.
+- The `hasUI == false` branch cannot be reached through RPC. Test it with the fake host
+  described in the Skill (`references/fakehost_test.go.txt`).
+- Effects the extension starts without awaiting are collected during a quiet period
+  (`settleMs`, default 150 ms, plus `tailMs` after the last step). An effect later than
+  that is not seen. Parallel exec calls arrive in a nondeterministic order.
+- Only declared commands are recorded. `exec-coverage` catches literal command names;
+  a computed name (`pi.exec(tool, ...)`) must be declared by hand and reviewed.
+- The host's own system prompt wording is not compared, only the extension's difference
+  from it. An extension that removes host text shows the removed text, which may differ
+  between Pi and PiG (a host-check failure to record, not to normalize).
+- The extension's stderr and log output are not in the trace.
+- Linux and macOS. The shims are POSIX symlinks; Windows is covered by the Skill's
+  Windows notes and `go vet`, not by this harness.
+- The harness needs `go` (it builds its shim and PiG builds Go extensions on first use)
+  and `node` (TypeScript lanes).
+
+## Use from a checkout
+
+```sh
+PIG_BIN=/path/to/pig npm run build:pigeq              # dist/bin/pigeq (a go.work resolves PiG's SDK)
+dist/bin/pigeq env --root /tmp/porting --pig /path/to/pig --pi /path/to/pi > /tmp/porting/env.sh && . /tmp/porting/env.sh
+pigeq run --scenarios <port>/port/scenarios --ts <original>.ts --go <port-dir>
+```
+
+MIT. The harness is original work; PiG's SDK surface table is quoted as data (rows
+listed with their revision in `eq/surface/go-gaps.md`).

package/extensions/extension-equivalence/cmd/pigeq/go.mod

@@ -0,0 +1,9 @@
+module github.com/MichaelKinsy/pigpen/extension-equivalence/cmd/pigeq
+
+go 1.26
+
+// A module of its own: PiG rejects an extension directory that holds both a factory and a
+// standalone main package, so the command line sits beside the factory, not in its module.
+require github.com/MichaelKinsy/pigpen/extension-equivalence v0.0.0
+
+replace github.com/MichaelKinsy/pigpen/extension-equivalence => ../..

package/extensions/extension-equivalence/cmd/pigeq/main.go

@@ -0,0 +1,504 @@
+// Command pigeq is the extension equivalence harness.
+//
+//	pigeq run    --scenarios DIR --ts FILE --go DIR --pi PI --pig PIG   oracle and port, live
+//	pigeq record --scenarios DIR --golden DIR --ts FILE --pi PI [--pig PIG]
+//	pigeq check  --scenarios DIR --golden DIR --go DIR --pig PIG        port against golden traces
+//	pigeq mutate --scenarios DIR --golden DIR --go DIR --pig PIG --mutations FILE [--unit --sdk-dir DIR]
+//	pigeq lane   --scenarios DIR --host pi|pig --bin EXE --ext PATH --out DIR   one lane, traces only
+//	pigeq gaps   --ts FILE|DIR | --go DIR [--surface FILE] [--accept-gaps FILE]
+//	                                                                    Pi APIs the Go SDK lacks (TS), or PiG-internal
+//	                                                                    imports, fuse hazards and SDK stand-ins (Go)
+//
+// The oracle is one of --ts (TypeScript original under Pi), --go-oracle (a Go original under
+// PiG) or --self (no original: record the port as its own regression baseline, never proof).
+//
+//	pigeq diff   WANT.jsonl GOT.jsonl
+//	pigeq env    --root DIR [--pig PIG] [--pi PI] [--source DIR] [--module DIR]...
+//	                                                                    print an isolated shell environment (source it);
+//	                                                                    with --pig and --module also writes DIR/go.work
+//	pigeq twins  list --tests DIR > ledger.json                         upstream test titles per file
+//	pigeq twins  check --ledger ledger.json --go DIR [--files a,b]       every title has a tw() twin or a named tskip()
+//	pigeq llm    --script turns.json [--log requests.jsonl]              serve the scripted model (prints its base URL)
+//	pigeq source --from PIG-REPO --rev REV --out DIR                    export a PiG revision as a one-commit git checkout
+//	                                                                    (PIG_SOURCE_ROOT for `pig piglet build`)
+//
+// PIGEQ_PI and PIGEQ_PIG supply the host executables. Exit status is 0 only when
+// every scenario passes (or, for mutate, every mutation is caught).
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/extension-equivalence/eq"
+)
+
+func main() {
+	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
+}
+
+func run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		fmt.Fprintln(stderr, "usage: pigeq run|record|check|mutate|lane|gaps|diff|env|source|twins|llm [flags]")
+		return 2
+	}
+	cmd, rest := args[0], args[1:]
+	if cmd == "env" || cmd == "source" {
+		return session(cmd, rest, stdout, stderr)
+	}
+	if cmd == "twins" {
+		return twins(rest, stdout, stderr)
+	}
+	if cmd == "llm" {
+		return llm(rest, stdout, stderr)
+	}
+	fs := flag.NewFlagSet("pigeq "+cmd, flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	var (
+		scenarios = fs.String("scenarios", "", "scenario file or directory")
+		golden    = fs.String("golden", "", "directory of golden traces")
+		ts        = fs.String("ts", "", "the original TypeScript extension (oracle)")
+		goDir     = fs.String("go", "", "the Go port directory (gaps: the Go source to scan)")
+		goOracle  = fs.String("go-oracle", "", "an original that is already a Go extension (oracle, run under PiG)")
+		self      = fs.Bool("self", false, "no original exists: record the port as its own regression baseline (not equivalence)")
+		pi        = fs.String("pi", os.Getenv("PIGEQ_PI"), "pi executable (default $PIGEQ_PI)")
+		pig       = fs.String("pig", os.Getenv("PIGEQ_PIG"), "pig executable (default $PIGEQ_PIG)")
+		out       = fs.String("out", "", "directory for recorded traces")
+		mutations = fs.String("mutations", "", "mutation list (JSON)")
+		skipHost  = fs.Bool("skip-host-check", false, "do not run the original under PiG")
+		host      = fs.String("host", "", "lane host: pi or pig")
+		bin       = fs.String("bin", "", "lane host executable")
+		ext       = fs.String("ext", "", "lane extension (TypeScript file or Go directory)")
+		surface   = fs.String("surface", os.Getenv("PIGEQ_SURFACE"), "PiG docs/extension-sdk-surface.md (default: embedded snapshot)")
+		accept    = fs.String("accept-gaps", "", "JSON object mapping an accepted gap symbol to its owner approval")
+		sdkDir    = fs.String("sdk-dir", os.Getenv("PIG_SDK_DIR"), "PiG's staged Go SDK (mutate: enables the unit-test layer)")
+		unitTests = fs.Bool("unit", false, "mutate: also run the port's go tests on each mutant first (needs --sdk-dir)")
+		builtin   = fs.Bool("builtin", false, "check, record --self: the port is compiled into --pig (a built Piglet Binary); load no extension directory")
+		unitOnly  = fs.Bool("unit-only", false, "mutate: judge mutants by the port's own go tests alone; no scenarios, golden traces or pig (for an original adapter)")
+		jobs      = fs.Int("jobs", 1, "mutate: how many mutants to run at once (each has its own copy)")
+		keep      = fs.Bool("keep", false, "keep each lane's run directory")
+		stepSecs  = fs.Int("step-timeout", 0, "seconds to wait for each scenario step (default 60; 20 for mutants)")
+	)
+	if err := fs.Parse(rest); err != nil {
+		return 2
+	}
+	var accepted map[string]string
+	if *accept != "" {
+		b, err := os.ReadFile(*accept)
+		if err == nil {
+			err = json.Unmarshal(b, &accepted)
+		}
+		if err != nil {
+			fmt.Fprintln(stderr, "pigeq: --accept-gaps:", err)
+			return 2
+		}
+	}
+	cfg := eq.Config{Surface: *surface, AcceptedGaps: accepted, Pi: *pi, Pig: *pig, TS: *ts, Go: *goDir, GoOracle: *goOracle, Self: *self, Builtin: *builtin, Out: *out, SkipHostCheck: *skipHost,
+		Options: eq.Options{Keep: *keep, Stderr: stderr, StepTimeout: time.Duration(*stepSecs) * time.Second}}
+	need := func(pairs ...string) bool {
+		for i := 0; i < len(pairs); i += 2 {
+			if pairs[i+1] == "" {
+				fmt.Fprintf(stderr, "pigeq %s: %s is required\n", cmd, pairs[i])
+				return false
+			}
+		}
+		return true
+	}
+	if cmd == "gaps" {
+		if (*ts == "") == (*goDir == "") {
+			fmt.Fprintln(stderr, "pigeq gaps: give --ts or --go (a TypeScript original or Go source), not both and not neither")
+			return 2
+		}
+		surf := ""
+		if *surface != "" {
+			b, err := os.ReadFile(*surface)
+			if err != nil {
+				fmt.Fprintln(stderr, err)
+				return 2
+			}
+			surf = string(b)
+		}
+		var gaps []eq.Gap
+		var err error
+		if *ts != "" {
+			if ok, oerr := eq.PathLooksLikeExtension(*ts); oerr == nil && !ok {
+				fmt.Fprint(stdout, eq.NotAnExtensionNote())
+				return 1
+			}
+			gaps, err = eq.ScanGapsPath(*ts, surf)
+		} else {
+			gaps, err = eq.ScanGoPath(*goDir, surf)
+		}
+		if err != nil {
+			fmt.Fprintln(stderr, err)
+			return 2
+		}
+		fmt.Fprint(stdout, eq.FormatGaps(gaps))
+		// An owner-approved exclusion (--accept-gaps) does not block; it is still listed.
+		if open := eq.Unaccepted(gaps, accepted); len(open) > 0 {
+			return 1
+		}
+		for _, g := range gaps {
+			if reason, ok := accepted[g.Symbol]; ok {
+				fmt.Fprintf(stdout, "ACCEPTED %s: %s\n", g.Symbol, reason)
+			}
+		}
+		return 0
+	}
+	if cmd == "diff" {
+		if fs.NArg() != 2 {
+			fmt.Fprintln(stderr, "usage: pigeq diff WANT.jsonl GOT.jsonl")
+			return 2
+		}
+		want, err := eq.ReadTrace(fs.Arg(0))
+		if err != nil {
+			fmt.Fprintln(stderr, err)
+			return 2
+		}
+		got, err := eq.ReadTrace(fs.Arg(1))
+		if err != nil {
+			fmt.Fprintln(stderr, err)
+			return 2
+		}
+		if d := eq.Diff(want, got); d != nil {
+			fmt.Fprintln(stdout, "DIFFERENT:", d)
+			return 1
+		}
+		fmt.Fprintf(stdout, "IDENTICAL (%d events)\n", len(want.Events))
+		return 0
+	}
+	if cmd == "mutate" && *builtin {
+		fmt.Fprintln(stderr, "pigeq mutate: cannot mutate a built binary; mutate the port's source directory (--go)")
+		return 2
+	}
+	if cmd == "mutate" && *unitOnly {
+		return mutateUnitOnly(cfg, *mutations, *sdkDir, *jobs, stdout, stderr, need)
+	}
+	if !need("--scenarios", *scenarios) {
+		return 2
+	}
+	scs, err := eq.LoadScenarios(*scenarios)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	var results []eq.Result
+	switch cmd {
+	case "run":
+		if !need("--go", *goDir, "--pig", *pig) {
+			return 2
+		}
+		results, err = eq.Run(scs, cfg)
+	case "lane":
+		if !need("--host", *host, "--bin", *bin, "--ext", *ext) {
+			return 2
+		}
+		results, err = eq.LaneTraces(scs, cfg, eq.Lane{Name: *host + "-lane", Host: *host, Bin: *bin, Ext: *ext})
+	case "record":
+		if !need("--golden", *golden) {
+			return 2
+		}
+		if *ts == "" && *goOracle == "" && !*self {
+			fmt.Fprintln(stderr, "pigeq record: give the oracle: --ts, --go-oracle or --self")
+			return 2
+		}
+		results, err = eq.Record(scs, cfg, *golden)
+	case "check":
+		if *builtin {
+			cfg.Builtin = true
+			if !need("--golden", *golden, "--pig", *pig) {
+				return 2
+			}
+		} else if !need("--golden", *golden, "--go", *goDir, "--pig", *pig) {
+			return 2
+		}
+		results, err = eq.Check(scs, cfg, *golden)
+	case "mutate":
+		if !need("--golden", *golden, "--go", *goDir, "--pig", *pig, "--mutations", *mutations) {
+			return 2
+		}
+		list, lerr := eq.LoadMutations(*mutations)
+		if lerr != nil {
+			fmt.Fprintln(stderr, lerr)
+			return 2
+		}
+		var unit *eq.UnitTest
+		if *unitTests {
+			if *sdkDir == "" {
+				fmt.Fprintln(stderr, "pigeq mutate: --unit needs --sdk-dir (or $PIG_SDK_DIR)")
+				return 2
+			}
+			unit = eq.NewUnitTest(*sdkDir)
+		}
+		cfg.Jobs = *jobs
+		mres, merr := eq.Mutate(scs, cfg, *golden, list, unit)
+		if merr != nil {
+			fmt.Fprintln(stderr, merr)
+			return 2
+		}
+		return reportMutations(stdout, mres)
+	default:
+		fmt.Fprintf(stderr, "pigeq: unknown command %q\n", cmd)
+		return 2
+	}
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	if !eq.WriteReport(stdout, results) {
+		return 1
+	}
+	return 0
+}
+
+// session implements the two commands that prepare a porting session.
+func session(cmd string, args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("pigeq "+cmd, flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	root := fs.String("root", "", "env: scratch root; home, pighome and agent live under it (default: a new private directory)")
+	pig := fs.String("pig", os.Getenv("PIGEQ_PIG"), "env: pig executable")
+	pi := fs.String("pi", os.Getenv("PIGEQ_PI"), "env: pi executable")
+	source := fs.String("source", os.Getenv("PIG_SOURCE_ROOT"), "env: git checkout of the PiG source the pig was built from")
+	var modules []string
+	fs.Func("module", "env: a Go module directory of the port (repeatable); needs --pig", func(v string) error {
+		abs, err := filepath.Abs(v)
+		modules = append(modules, abs)
+		return err
+	})
+	from := fs.String("from", "", "source: a PiG git repository")
+	rev := fs.String("rev", "", "source: the revision to export (a full commit)")
+	out := fs.String("out", "", "source: the new directory")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	if cmd == "source" {
+		if *from == "" || *rev == "" || *out == "" {
+			fmt.Fprintln(stderr, "pigeq source: --from, --rev and --out are required")
+			return 2
+		}
+		abs, err := filepath.Abs(*out)
+		if err == nil {
+			err = eq.SnapshotSource(*from, *rev, abs)
+		}
+		if err != nil {
+			fmt.Fprintln(stderr, "pigeq source:", err)
+			return 2
+		}
+		fmt.Fprintf(stdout, "export PIG_SOURCE_ROOT=%s\n", abs)
+		return 0
+	}
+	if *root == "" {
+		// A private directory per call: lanes that each picked /tmp/<name> overwrote one another's env.sh.
+		dir, err := os.MkdirTemp("", "pigeq-")
+		if err != nil {
+			fmt.Fprintln(stderr, "pigeq env:", err)
+			return 2
+		}
+		*root = dir
+	}
+	abs, err := filepath.Abs(*root)
+	if err != nil {
+		fmt.Fprintln(stderr, "pigeq env:", err)
+		return 2
+	}
+	if *pi != "" && *pig != "" {
+		if err := eq.CheckPiVersion(*pi, *pig); err != nil {
+			fmt.Fprintln(stderr, "pigeq env:", err)
+			return 2
+		}
+	}
+	spec, err := eq.DiscoverToolchain()
+	if err != nil {
+		fmt.Fprintln(stderr, "pigeq env:", err)
+		return 2
+	}
+	spec.Root, spec.Pig, spec.Pi, spec.Source = abs, *pig, *pi, *source
+	if *pig != "" && len(modules) > 0 {
+		sdk, err := eq.SDKPath(*pig, abs)
+		if err == nil {
+			spec.SDKDir, spec.GoWork = sdk, filepath.Join(abs, "go.work")
+			err = eq.WriteGoWork(spec.GoWork, sdk, modules)
+		}
+		if err != nil {
+			fmt.Fprintln(stderr, "pigeq env:", err)
+			return 2
+		}
+	}
+	fmt.Fprint(stdout, eq.EnvScript(spec))
+	return 0
+}
+
+// twins implements `pigeq twins list|check`.
+func twins(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 || (args[0] != "list" && args[0] != "check") {
+		fmt.Fprintln(stderr, "usage: pigeq twins list --tests DIR | pigeq twins check --ledger FILE --go DIR [--files a,b] [--deferred slices.json] [--max-same-reason N]")
+		return 2
+	}
+	sub := args[0]
+	fs := flag.NewFlagSet("pigeq twins "+sub, flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	tests := fs.String("tests", "", "list: the upstream test directory")
+	ledgerPath := fs.String("ledger", "", "check: the ledger written by list")
+	goDir := fs.String("go", "", "check: the port directory with the Go twins")
+	files := fs.String("files", "", "check: only these ledger files (the slice shipped so far), comma separated")
+	deferred := fs.String("deferred", "", "check: JSON map of ledger file -> reason; the file's cases without a twin or named skip are deferred to a later slice (stated once)")
+	same := fs.Int("max-same-reason", 0, "check: most skips that may share one reason (default 3)")
+	twinFn := fs.String("twin", "tw", "check: name of the twin helper")
+	skipFn := fs.String("skip", "tskip", "check: name of the named-skip helper")
+	if err := fs.Parse(args[1:]); err != nil {
+		return 2
+	}
+	if sub == "list" {
+		if *tests == "" {
+			fmt.Fprintln(stderr, "pigeq twins list: --tests is required")
+			return 2
+		}
+		ledger, err := eq.ListUpstreamTitles(*tests)
+		if err != nil {
+			fmt.Fprintln(stderr, "pigeq twins list:", err)
+			return 2
+		}
+		enc := json.NewEncoder(stdout)
+		enc.SetIndent("", " ")
+		if err := enc.Encode(ledger); err != nil {
+			fmt.Fprintln(stderr, err)
+			return 2
+		}
+		return 0
+	}
+	if *ledgerPath == "" || *goDir == "" {
+		fmt.Fprintln(stderr, "pigeq twins check: --ledger and --go are required")
+		return 2
+	}
+	var ledger map[string][]string
+	b, err := os.ReadFile(*ledgerPath)
+	if err == nil {
+		err = json.Unmarshal(b, &ledger)
+	}
+	if err != nil {
+		fmt.Fprintln(stderr, "pigeq twins check:", err)
+		return 2
+	}
+	opts := eq.TwinOptions{MaxSameReason: *same, TwinFunc: *twinFn, SkipFunc: *skipFn}
+	if *deferred != "" {
+		db, derr := os.ReadFile(*deferred)
+		if derr == nil {
+			derr = json.Unmarshal(db, &opts.Deferred)
+		}
+		if derr != nil {
+			fmt.Fprintln(stderr, "pigeq twins check:", derr)
+			return 2
+		}
+	}
+	if *files != "" {
+		opts.Files = strings.Split(*files, ",")
+	}
+	rep, err := eq.CheckTwins(ledger, *goDir, opts)
+	if err != nil {
+		fmt.Fprintln(stderr, "pigeq twins check:", err)
+		return 2
+	}
+	fmt.Fprint(stdout, rep.Summary())
+	if !rep.OK() {
+		return 1
+	}
+	return 0
+}
+
+// llm serves the scripted OpenAI-compatible model until stdin closes or a signal arrives.
+func llm(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("pigeq llm", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	script := fs.String("script", "", "JSON array of turns: [{\"text\":\"...\"},{\"toolCalls\":[{\"name\":\"bash\",\"arguments\":{}}]}]")
+	logPath := fs.String("log", "", "write each request as a JSON line to this file (default: none)")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	if *script == "" {
+		fmt.Fprintln(stderr, "pigeq llm: --script is required")
+		return 2
+	}
+	var turns []eq.Turn
+	b, err := os.ReadFile(*script)
+	if err == nil {
+		err = json.Unmarshal(b, &turns)
+	}
+	if err != nil {
+		fmt.Fprintln(stderr, "pigeq llm:", err)
+		return 2
+	}
+	var log io.Writer
+	if *logPath != "" {
+		f, err := os.Create(*logPath)
+		if err != nil {
+			fmt.Fprintln(stderr, "pigeq llm:", err)
+			return 2
+		}
+		defer f.Close()
+		log = f
+	}
+	url, stop, err := eq.ServeLLM(turns, log)
+	if err != nil {
+		fmt.Fprintln(stderr, "pigeq llm:", err)
+		return 2
+	}
+	defer stop()
+	fmt.Fprintln(stdout, url)
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
+	done := make(chan struct{})
+	go func() { _, _ = io.Copy(io.Discard, os.Stdin); close(done) }()
+	select {
+	case <-sig:
+	case <-done:
+	}
+	return 0
+}
+
+// reportMutations prints one status per mutant and the summary line; it returns the exit status.
+func reportMutations(stdout io.Writer, mres []eq.MutationResult) int {
+	survived := 0
+	for _, m := range mres {
+		status := "KILLED  "
+		if m.Invalid {
+			status = "INVALID "
+			survived++
+		} else if !m.Killed {
+			status = "SURVIVED"
+			survived++
+		}
+		fmt.Fprintf(stdout, "%s %s\n         %s\n", status, m.Mutation.Name, m.Detail)
+	}
+	fmt.Fprintf(stdout, "%d mutation(s), %d not killed\n", len(mres), survived)
+	if survived > 0 {
+		return 1
+	}
+	return 0
+}
+
+// mutateUnitOnly runs mutants against the port's own tests only.
+func mutateUnitOnly(cfg eq.Config, mutations, sdkDir string, jobs int, stdout, stderr io.Writer, need func(pairs ...string) bool) int {
+	if !need("--go", cfg.Go, "--mutations", mutations, "--sdk-dir", sdkDir) {
+		return 2
+	}
+	list, err := eq.LoadMutations(mutations)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	cfg.UnitOnly, cfg.Jobs = true, jobs
+	mres, err := eq.Mutate(nil, cfg, "", list, eq.NewUnitTest(sdkDir))
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	return reportMutations(stdout, mres)
+}