fix: fail closed on unusable Codex auth during sandbox auth merge

When reusing a Codex sandbox, the workspace-restore step now performs
an auth-merge check before adopting the sandbox's auth.json. The merge
fails closed when:

- host or sandbox Codex auth is unusable (missing token or account)
- the subscription payload shapes differ between host and sandbox
- subscription account identities do not match

Additional hardening: node absence on PATH during the embedded decision
script now exits non-zero instead of silently falling through. Co-change
comments link parseAuth (the embedded script) to hasUsableAuthPayload
(codex-home.ts) so a future auth-format change cannot silently diverge
between the two implementations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

tools/agent-shim/.gitignore

@@ -0,0 +1,2 @@
+/bin/
+/agent-shim

tools/agent-shim/go.mod

@@ -0,0 +1,3 @@
+module github.com/paperclipai/paperclip/tools/agent-shim
+
+go 1.22

tools/agent-shim/main.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"syscall"
+)
+
+const (
+	defaultRuntimeCommandPath = "/run/paperclip/runtime-command.json"
+)
+
+func main() {
+	specPath := flag.String("spec", defaultRuntimeCommandPath, "path to AdapterRuntimeCommandSpec JSON")
+	adapterType := flag.String("adapter", "", "adapter type (informational; e.g. claude_local)")
+	flag.Parse()
+
+	spec, err := loadRuntimeCommandSpec(*specPath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[shim] cannot read runtime command spec: %v\n", err)
+		os.Exit(2)
+	}
+
+	resolved, err := exec.LookPath(spec.Command)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[shim] adapter command %q not found in PATH (adapter=%s)\n", spec.Command, *adapterType)
+		os.Exit(127)
+	}
+
+	// Build argv (resolved binary as argv[0])
+	argv := append([]string{resolved}, spec.Args...)
+
+	// syscall.Exec replaces this process; SIGTERM from k8s reaches the adapter directly.
+	if err := syscall.Exec(resolved, argv, os.Environ()); err != nil {
+		fmt.Fprintf(os.Stderr, "[shim] exec %q failed: %v\n", resolved, err)
+		os.Exit(126)
+	}
+}

tools/agent-shim/main_test.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadRuntimeCommandSpec_OK(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "spec.json")
+	_ = os.WriteFile(p, []byte(`{"command":"claude-code","args":["--print"]}`), 0o600)
+	spec, err := loadRuntimeCommandSpec(p)
+	if err != nil {
+		t.Fatalf("expected ok, got %v", err)
+	}
+	if spec.Command != "claude-code" || len(spec.Args) != 1 {
+		t.Fatalf("unexpected spec: %+v", spec)
+	}
+}
+
+func TestLoadRuntimeCommandSpec_MissingCommand(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "spec.json")
+	_ = os.WriteFile(p, []byte(`{"command":""}`), 0o600)
+	if _, err := loadRuntimeCommandSpec(p); err == nil {
+		t.Fatal("expected error for empty command")
+	}
+}

tools/agent-shim/runtime_command.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+)
+
+type RuntimeCommandSpec struct {
+	Command        string   `json:"command"`
+	Args           []string `json:"args"`
+	DetectCommand  string   `json:"detectCommand,omitempty"`
+	InstallCommand string   `json:"installCommand,omitempty"`
+}
+
+func loadRuntimeCommandSpec(path string) (*RuntimeCommandSpec, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var spec RuntimeCommandSpec
+	if err := json.Unmarshal(b, &spec); err != nil {
+		return nil, err
+	}
+	if spec.Command == "" {
+		return nil, errors.New("runtime-command.json has empty 'command'")
+	}
+	return &spec, nil
+}