journeymetrics: fold dispatched-ensign transcript into --read adoption (#448)

The --read adoption counters (status_read_calls/scoped_read_calls) parsed
only the FO front-door stream, but `status --read` adoption is principally
an ENSIGN behavior — the ensign runs as a separate sub-agent session whose
transcript lands on disk, never in the FO stream. So four real FO captures
all measured 0/0.

- FoldEnsignReadAdoption sums each ensign transcript's two adoption counters
  onto the FO observation (parse-per-transcript-then-sum, so per-session tool
  IDs never cross-count). turns/tokens/tool_calls keep FO-front-door semantics.
- commandInvokesStatusRead now normalizes the launcher token preceding
  `status` (strip surrounding quotes, then accept a literal launcher name or
  the SPACEDOCK_BIN variable family), so the dominant real forms
  (spacedock_launcher, ./spacedock) and the contract-canonical quoted
  "${SPACEDOCK_BIN:-spacedock}" all count. $SPACEDOCK stays unrecognized.
- The live harness globs the ensign subagents/agent-*.jsonl under the FO
  session's subagents dir and folds them in emitClaudeScenarioMetrics.

Re-parsing the spike's real ensign transcript now yields status_read_calls=2
(was 0) and scoped_read_calls=6.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: clkao

internal/ensigncycle/claude_live_runner_test.go

@@ -98,6 +98,14 @@ type liveResult struct {
 	stream       string
 	artifactDir  string
 	duration     time.Duration
+	// configDir and cwd locate the dispatched-ensign sub-agent transcripts on disk
+	// (under {configDir}/projects/{encode(cwd)}/{FO-session-id}/subagents), so the
+	// journey-metrics fold can observe the ensign's --read adoption. cwd is the
+	// EvalSymlinks-resolved FO working dir — the form Claude Code encodes into the
+	// projects path. Empty on transports that do not record them (the pty driver),
+	// so the fold no-ops to FO-front-door counts.
+	configDir string
+	cwd       string
 }
 
 type claudeLiveScenario struct {
@@ -382,8 +390,18 @@ func (r claudeLiveRunner) run(t *testing.T, scenario sharedRuntimeScenario, work
 	// fresh slice (never a mutation of the shared r.env) keeps the parallel
 	// invocations race-free.
 	cmd.Env = r.env
+	configDir, _ := envValue(r.env, "CLAUDE_CONFIG_DIR")
 	if base, ok := envValue(r.env, "CLAUDE_CONFIG_DIR"); ok {
-		cmd.Env = withClaudeConfigDir(r.env, filepath.Join(base, scenario.name))
+		configDir = filepath.Join(base, scenario.name)
+		cmd.Env = withClaudeConfigDir(r.env, configDir)
+	}
+
+	// The resolved cwd is what Claude Code encodes into its projects path; the FO
+	// subprocess runs in workflowRoot, so resolve its symlinks (macOS t.TempDir is
+	// under /var -> /private/var) to match the on-disk subagents dir.
+	resolvedCwd := workflowRoot
+	if resolved, err := filepath.EvalSymlinks(workflowRoot); err == nil {
+		resolvedCwd = resolved
 	}
 
 	// stdout carries the stream-json transcript the watcher drains for liveness;
@@ -447,6 +465,8 @@ func (r claudeLiveRunner) run(t *testing.T, scenario sharedRuntimeScenario, work
 		stream:       stream,
 		artifactDir:  artifactDir,
 		duration:     duration,
+		configDir:    configDir,
+		cwd:          resolvedCwd,
 	}
 }
 

internal/ensigncycle/journey_metrics_live_test.go

@@ -5,6 +5,7 @@ package ensigncycle
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/spacedock-dev/spacedock/internal/journeymetrics"
@@ -22,6 +23,14 @@ func emitClaudeScenarioMetrics(t *testing.T, scenario sharedRuntimeScenario, res
 	}
 	observation := parsed.Observation
 	observation.Duration = result.duration
+	// Fold the dispatched-ensign sub-agent transcripts' --read adoption onto the FO
+	// front-door counts: `status --read` adoption is principally an ensign behavior,
+	// and the ensign runs as a separate sub-agent session whose transcript lands on
+	// disk, never in result.stream.
+	observation, err = journeymetrics.FoldEnsignReadAdoption(observation, ensignTranscripts(result))
+	if err != nil {
+		t.Fatalf("fold ensign --read adoption for %s: %v", scenario.name, err)
+	}
 	record := journeymetrics.BuildRecord(journeymetrics.JourneySpec{
 		ScenarioID: scenario.name,
 		Source:     "live-harness",
@@ -36,6 +45,36 @@ func emitClaudeScenarioMetrics(t *testing.T, scenario sharedRuntimeScenario, res
 	}
 }
 
+// ensignTranscripts reads the dispatched-ensign sub-agent transcripts for this
+// journey from disk. The ensign runs as a separate sub-agent session whose
+// transcript lands under the FO session's subagents dir — never in result.stream —
+// so the glob mirrors the proven scanSubagentMeta shape:
+// {configDir}/projects/{encode(cwd)}/{FO-session-id}/subagents/agent-*.jsonl. The
+// FO session id comes from the stream's system/init event. Returns nil when the run
+// did not record a config dir / cwd / session id (e.g. the pty transport), so the
+// fold no-ops to FO-front-door counts.
+func ensignTranscripts(result liveResult) [][]byte {
+	if result.configDir == "" || result.cwd == "" {
+		return nil
+	}
+	sessionID := initEventSessionID(strings.Split(result.stream, "\n"))
+	if sessionID == "" {
+		return nil
+	}
+	pattern := filepath.Join(result.configDir, "projects",
+		encodeProjectDir(result.cwd), sessionID, "subagents", "agent-*.jsonl")
+	matches, _ := filepath.Glob(pattern)
+	var transcripts [][]byte
+	for _, p := range matches {
+		data, err := os.ReadFile(p)
+		if err != nil {
+			continue
+		}
+		transcripts = append(transcripts, data)
+	}
+	return transcripts
+}
+
 func emitCodexScenarioMetrics(t *testing.T, scenario sharedRuntimeScenario, result codexScenarioResult) {
 	t.Helper()
 	dir := os.Getenv("SPACEDOCK_JOURNEY_METRICS_DIR")

internal/journeymetrics/readadoption.go

@@ -7,13 +7,43 @@ import (
 	"strings"
 )
 
-// statusReadLaunchers are the command prefixes under which `status` is the
-// spacedock subcommand: the two installed binaries plus the
-// ${SPACEDOCK_BIN:-spacedock} form the fetch commands emit.
+// statusReadLaunchers are the literal command names under which `status` is the
+// spacedock subcommand: the two installed binaries, the `./spacedock` dev build,
+// and the `spacedock_launcher` shell function the dispatch fetch commands define
+// and call. The ${SPACEDOCK_BIN:-spacedock} variable form is recognized separately
+// (launcherIsSpacedock) since it is a value reference, not a fixed name.
 var statusReadLaunchers = map[string]bool{
-	"spacedock":                   true,
-	"sd":                          true,
-	"${SPACEDOCK_BIN:-spacedock}": true,
+	"spacedock":          true,
+	"sd":                 true,
+	"./spacedock":        true,
+	"spacedock_launcher": true,
+}
+
+// launcherIsSpacedock reports whether the token immediately preceding `status`
+// launches the spacedock binary. It normalizes the token first — stripping one
+// layer of surrounding quotes, so the contract-canonical quoted
+// "${SPACEDOCK_BIN:-spacedock}" form (shared-core invariant) is recognized — then
+// accepts either a literal launcher name or any reference to the SPACEDOCK_BIN
+// variable family (${SPACEDOCK_BIN:-spacedock}, quoted or not). $SPACEDOCK is a
+// legacy variable, NOT the SPACEDOCK_BIN family, so it stays unrecognized.
+func launcherIsSpacedock(tok string) bool {
+	tok = stripSurroundingQuotes(tok)
+	if statusReadLaunchers[tok] {
+		return true
+	}
+	return strings.Contains(tok, "SPACEDOCK_BIN")
+}
+
+// stripSurroundingQuotes removes one matching pair of surrounding single or double
+// quotes from s, leaving an unquoted or unbalanced token untouched.
+func stripSurroundingQuotes(s string) string {
+	if len(s) >= 2 {
+		q := s[0]
+		if (q == '"' || q == '\'') && s[len(s)-1] == q {
+			return s[1 : len(s)-1]
+		}
+	}
+	return s
 }
 
 // commandInvokesStatusRead reports whether cmd invokes the spacedock `status`
@@ -28,7 +58,7 @@ func commandInvokesStatusRead(cmd string) bool {
 		if tok != "status" {
 			continue
 		}
-		isSubcommand := i == 0 || statusReadLaunchers[tokens[i-1]]
+		isSubcommand := i == 0 || launcherIsSpacedock(tokens[i-1])
 		if !isSubcommand {
 			continue
 		}
@@ -41,6 +71,31 @@ func commandInvokesStatusRead(cmd string) bool {
 	return false
 }
 
+// FoldEnsignReadAdoption sums each dispatched-ensign sub-agent transcript's
+// `status --read` and scoped-`Read` counts onto obs's two --read adoption
+// counters. `status --read` adoption is principally an ensign behavior, and the
+// ensign runs as a separate sub-agent session whose transcript never reaches the
+// FO front-door stream — so the metric must fold those transcripts to observe the
+// surface the contract sites actually steer.
+//
+// Each transcript is parsed independently and its counts SUMMED (not concatenated
+// then parsed): tool IDs are unique per session, so summing cannot cross-count and
+// the per-stream multi-delta tool-ID dedup stays correct within each transcript.
+// Concatenating would risk tool-ID collision across sessions. Only the two
+// adoption counters fold; turns/tokens/tool_calls keep their FO-front-door
+// semantics.
+func FoldEnsignReadAdoption(obs Observation, transcripts [][]byte) (Observation, error) {
+	for _, transcript := range transcripts {
+		parsed, err := ParseClaudeJSONL(transcript)
+		if err != nil {
+			return obs, err
+		}
+		obs.StatusReadCalls += parsed.Observation.StatusReadCalls
+		obs.ScopedReadCalls += parsed.Observation.ScopedReadCalls
+	}
+	return obs, nil
+}
+
 // readInputIsScoped reports whether a Read tool_use input is a scoped read — one
 // carrying a non-zero offset or limit (the line-range fields). A whole-file Read
 // carries only file_path, so neither field is present and the read is unscoped.

internal/journeymetrics/readadoption_test.go

@@ -77,6 +77,63 @@ func TestCodexCharacterizationSurfacesStatusReadCalls(t *testing.T) {
 	}
 }
 
+func TestFoldEnsignReadAdoption(t *testing.T) {
+	// FO front-door stream with a known baseline: a plain `spacedock status` (no
+	// --read) and one scoped Read (offset/limit). Baseline = (status_read=0,
+	// scoped_read=1) — `status --read` adoption is principally an ENSIGN behavior,
+	// so the FO front-door alone registers ~0.
+	foStream := `{"type":"system","subtype":"init","model":"claude-sonnet-4-6"}
+{"type":"assistant","message":{"id":"msg_fo1","model":"claude-sonnet-4-6","usage":{"input_tokens":100},"content":[{"type":"tool_use","id":"toolu_fo_status","name":"Bash","input":{"command":"spacedock status --json"}}]}}
+{"type":"assistant","message":{"id":"msg_fo2","model":"claude-sonnet-4-6","usage":{"input_tokens":120},"content":[{"type":"tool_use","id":"toolu_fo_read","name":"Read","input":{"file_path":"/path/entity.md","offset":10,"limit":20}}]}}`
+	parsed, err := ParseClaudeJSONL([]byte(foStream))
+	if err != nil {
+		t.Fatalf("ParseClaudeJSONL (FO front-door): %v", err)
+	}
+	baseline := parsed.Observation
+	if baseline.StatusReadCalls != 0 || baseline.ScopedReadCalls != 1 {
+		t.Fatalf("FO baseline counts = (%d,%d), want (0,1)", baseline.StatusReadCalls, baseline.ScopedReadCalls)
+	}
+
+	// A dispatched-ensign sub-agent transcript carrying one recognized-form
+	// `spacedock_launcher status --read` Bash call + one scoped Read. The on-disk
+	// agent-*.jsonl shape carries extra top-level fields (parentUuid, agentId, …)
+	// the map[string]json.RawMessage decode ignores.
+	ensignTranscript := `{"parentUuid":"p","agentId":"a1","type":"assistant","message":{"id":"msg_en1","model":"claude-sonnet-4-6","usage":{"input_tokens":80},"content":[{"type":"tool_use","id":"toolu_en_status","name":"Bash","input":{"command":"spacedock_launcher status --read /path/entity.md --json"}}]}}
+{"parentUuid":"p","agentId":"a1","type":"assistant","message":{"id":"msg_en2","model":"claude-sonnet-4-6","usage":{"input_tokens":90},"content":[{"type":"tool_use","id":"toolu_en_read","name":"Read","input":{"file_path":"/path/entity.md","offset":40,"limit":12}}]}}`
+
+	folded, err := FoldEnsignReadAdoption(baseline, [][]byte{[]byte(ensignTranscript)})
+	if err != nil {
+		t.Fatalf("FoldEnsignReadAdoption: %v", err)
+	}
+	// Both the ensign's status --read and its scoped Read fold onto the FO counts.
+	if folded.StatusReadCalls != 1 || folded.ScopedReadCalls != 2 {
+		t.Errorf("folded counts = (%d,%d), want (1,2)", folded.StatusReadCalls, folded.ScopedReadCalls)
+	}
+	// Non-tautological by perturbation: the fold moved BOTH counters strictly above
+	// the FO-only baseline. With the fold removed (a no-op FoldEnsignReadAdoption)
+	// the counts stay at the baseline (0,1) and this assertion fails — the baseline
+	// can move the wrong way, so a passing assertion proves the ensign contribution
+	// was actually folded in, not that the numbers happen to match.
+	if folded.StatusReadCalls <= baseline.StatusReadCalls || folded.ScopedReadCalls <= baseline.ScopedReadCalls {
+		t.Errorf("fold did not raise counts above FO-only baseline (%d,%d) -> (%d,%d)",
+			baseline.StatusReadCalls, baseline.ScopedReadCalls, folded.StatusReadCalls, folded.ScopedReadCalls)
+	}
+
+	// Zero case: an ensign transcript carrying NEITHER a status --read (a plain
+	// `spacedock status`) NOR a scoped Read (a whole-file Read) folds to exactly the
+	// FO-only baseline.
+	noAdoption := `{"type":"assistant","message":{"id":"msg_en3","model":"claude-sonnet-4-6","usage":{"input_tokens":70},"content":[{"type":"tool_use","id":"toolu_en_plain","name":"Bash","input":{"command":"spacedock status --json"}}]}}
+{"type":"assistant","message":{"id":"msg_en4","model":"claude-sonnet-4-6","usage":{"input_tokens":75},"content":[{"type":"tool_use","id":"toolu_en_full","name":"Read","input":{"file_path":"/path/entity.md"}}]}}`
+	zero, err := FoldEnsignReadAdoption(baseline, [][]byte{[]byte(noAdoption)})
+	if err != nil {
+		t.Fatalf("FoldEnsignReadAdoption (zero case): %v", err)
+	}
+	if zero.StatusReadCalls != baseline.StatusReadCalls || zero.ScopedReadCalls != baseline.ScopedReadCalls {
+		t.Errorf("zero-case counts = (%d,%d), want FO-only baseline (%d,%d)",
+			zero.StatusReadCalls, zero.ScopedReadCalls, baseline.StatusReadCalls, baseline.ScopedReadCalls)
+	}
+}
+
 func TestCommandInvokesStatusRead(t *testing.T) {
 	cases := []struct {
 		name string
@@ -89,6 +146,14 @@ func TestCommandInvokesStatusRead(t *testing.T) {
 		{"sd launcher", "sd status --read /path/entity.md", true},
 		{"SPACEDOCK_BIN launcher", "${SPACEDOCK_BIN:-spacedock} status --read /path/entity.md", true},
 		{"bare status", "status --read /path/entity.md", true},
+		// The dominant real launcher forms the dispatch fetch commands emit: the
+		// spacedock_launcher shell function and the ./spacedock dev build.
+		{"spacedock_launcher function", "spacedock_launcher status --read /path/entity.md", true},
+		{"dev build ./spacedock", "./spacedock status --read /path/entity.md", true},
+		// The contract-canonical QUOTED launcher (shared-core invariant). The exact-
+		// token map dropped it; normalization strips the surrounding quotes so it
+		// counts — the M10 regression guard.
+		{"quoted SPACEDOCK_BIN launcher", `"${SPACEDOCK_BIN:-spacedock}" status --read /path/entity.md`, true},
 		// Flag order independence: --read after another flag still counts.
 		{"flag order independent", "spacedock status --json --read /path/entity.md", true},
 		// --json default appears too; the --read token anywhere after status counts.
@@ -104,6 +169,11 @@ func TestCommandInvokesStatusRead(t *testing.T) {
 		{"echo quoted status read", "echo 'status --read'", false},
 		// --read on a non-status command is not a status --read.
 		{"readonly other flag", "spacedock dispatch build --readme", false},
+		// A launcher token alone, with no following status --read, does not match.
+		{"launcher token alone", "spacedock_launcher", false},
+		// $SPACEDOCK is a legacy non-canonical variable, NOT the SPACEDOCK_BIN family
+		// the contract pins, so it stays unrecognized.
+		{"legacy SPACEDOCK var", "$SPACEDOCK status --read /path/entity.md", false},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {