hstack 0.7.1 → 0.16.0

package/template/scripts/telemetry/parsers/sidecars.py

@@ -0,0 +1,61 @@
+"""Load the per-change telemetry sidecars written by the five emitting Skills.
+
+Sidecars live at `hstack/specs/changes/<change-id>/.telemetry/*.json` and are
+derivative, gitignored, and never authoritative (ADR-0001). This parser only
+reads them; a malformed or absent sidecar is skipped, never repaired.
+
+Schema versions (see `templates/telemetry-sidecar.md`):
+  1 — no phase window. Reads as *unmeasured*: `phase_usage` returns None.
+  2 — carries `session_id`, `phase_opened_at`, `phase_closed_at` (ADR-0009).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def load_sidecars(hstack_root: Path) -> list[dict]:
+    """Every sidecar under every change folder, sorted by change then filename.
+
+    Each entry: {path, change_id, file, skill, phase_id, schema_version, data}.
+    `skill` and `phase_id` fall back to the filename when the payload omits them
+    (`implement-<phase-id>.json`), so a hand-truncated sidecar still groups.
+    """
+    out: list[dict] = []
+    changes_dir = hstack_root / "specs" / "changes"
+    if not changes_dir.is_dir():
+        return out
+    for change_dir in sorted(changes_dir.iterdir()):
+        if not change_dir.is_dir():
+            continue
+        telemetry_dir = change_dir / ".telemetry"
+        if not telemetry_dir.is_dir():
+            continue
+        for f in sorted(telemetry_dir.glob("*.json")):
+            data = _read_json(f)
+            if data is None:
+                continue
+            stem = f.stem
+            skill = data.get("skill") or f"hstack-{stem.split('-')[0]}"
+            phase_id = data.get("phase_id")
+            if phase_id is None and stem.startswith("implement-"):
+                phase_id = stem[len("implement-"):]
+            out.append({
+                "path": f,
+                "file": f.name,
+                "change_id": data.get("change_id") or change_dir.name,
+                "skill": skill,
+                "phase_id": phase_id,
+                "schema_version": data.get("schema_version"),
+                "data": data,
+            })
+    return out
+
+
+def _read_json(path: Path) -> dict | None:
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return loaded if isinstance(loaded, dict) else None

package/template/scripts/telemetry/parsers/transcripts.py

@@ -1,8 +1,15 @@
 """Walk Claude Code transcript JSONL files for token economics and halt signals.
 
-Generalized from scripts/audit-token-usage.py. Same cost-score weighting; same
-classify-by-Skill heuristic. Adds: halt-sentinel detection, per-session
-start/end timestamps, cwd grouping for Conductor worktree dedup.
+Generalized from scripts/audit-token-usage.py. Same cost-score weighting. Adds:
+halt-sentinel detection, per-session start/end timestamps, cwd grouping for
+Conductor worktree dedup, and (ADR-0009) per-phase usage summation bounded by a
+sidecar's phase window.
+
+Session→Skill attribution reads *structured invocation markers only* — the
+`<command-name>` tag the harness writes for a slash command, and `Skill`
+tool_use blocks. Free text is never matched: a prompt that merely mentions
+`/hstack:coord` used to capture the whole session, which credited `coord` with
+roughly half of all measured cache-read tokens (ADR-0009 § Context, defect 2).
 """
 
 from __future__ import annotations
@@ -10,18 +17,27 @@ from __future__ import annotations
 import json
 import re
 from collections import defaultdict
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterable
 
+from telemetry.session_id import transcript_for_session
+
 
 PROJECTS_ROOT = Path.home() / ".claude" / "projects"
 
-HSTACK_SLASH = re.compile(r"/hstack:([a-z][a-z0-9\-]*)")
-HSTACK_CMD_TAG = re.compile(r"<command-name>/?hstack:?-?([a-z][a-z0-9\-]*)</command-name>")
+# Structured markers only. `<command-name>` is emitted by the harness around a
+# slash-command invocation; both the `/hstack:foo` and `/hstack-foo` spellings
+# appear in real transcripts.
+HSTACK_CMD_TAG = re.compile(r"<command-name>/?hstack[:\-]([a-z][a-z0-9\-]*)</command-name>")
+# `Skill` tool_use input, optionally namespaced by a plugin prefix.
+HSTACK_SKILL_NAME = re.compile(r"^(?:[A-Za-z0-9_.\-]+:)?hstack[:\-]([a-z][a-z0-9\-]*)$")
 SUBAGENT_TYPE = re.compile(r'"subagent_type"\s*:\s*"([a-z][a-z0-9\-]*)"')
 HALT_SENTINEL = re.compile(r"HSTACK-HALT:\s*reason=([a-z-]+)", re.IGNORECASE)
 
+USAGE_KEYS = ("input_tokens", "cache_creation_input_tokens",
+              "cache_read_input_tokens", "output_tokens")
+
 
 def message_text(msg) -> str:
     if msg is None:
@@ -91,20 +107,58 @@ def load_session(path: Path) -> list[dict]:
     return out
 
 
+def skill_tool_uses(msg) -> list[str]:
+    """hstack Skill names invoked via a `Skill` tool_use block in this message.
+
+    Structural walk, not a regex over flattened text: the marker is the block's
+    `type`/`name`/`input.skill` triple, which prose cannot forge.
+    """
+    if not isinstance(msg, dict):
+        return []
+    content = msg.get("content")
+    if not isinstance(content, list):
+        return []
+    out = []
+    for blk in content:
+        if not isinstance(blk, dict):
+            continue
+        if blk.get("type") != "tool_use" or blk.get("name") != "Skill":
+            continue
+        inp = blk.get("input")
+        name = inp.get("skill") if isinstance(inp, dict) else None
+        if not isinstance(name, str):
+            continue
+        m = HSTACK_SKILL_NAME.match(name.strip())
+        if m:
+            out.append(m.group(1))
+    return out
+
+
 def classify_session(records: list[dict]) -> tuple[str | None, set[str], list[str]]:
-    """Return (skill_name, set of subagent types invoked, halt reasons)."""
+    """Return (skill_name, set of subagent types invoked, halt reasons).
+
+    `skill_name` is the first hstack Skill invoked through a structured marker —
+    a `<command-name>` tag or a `Skill` tool_use block. A session carrying
+    neither returns `None` and is reported as *unattributed* (ADR-0009 piece 3);
+    it is never captured by whatever hstack command its prompt happened to name.
+    """
     skill = None
     subagents: set[str] = set()
     halts: list[str] = []
     for r in records:
         t = r.get("type")
-        if t == "user" and skill is None:
-            text = message_text(r.get("message"))
-            m = HSTACK_CMD_TAG.search(text) or HSTACK_SLASH.search(text)
-            if m:
-                skill = m.group(1)
+        if t == "user":
+            if skill is None:
+                m = HSTACK_CMD_TAG.search(message_text(r.get("message")))
+                if m:
+                    skill = m.group(1)
         elif t == "assistant":
-            text = message_text(r.get("message"))
+            msg = r.get("message")
+            if skill is None:
+                invoked = skill_tool_uses(msg)
+                if invoked:
+                    skill = invoked[0]
+            text = message_text(msg)
             for sa in SUBAGENT_TYPE.findall(text):
                 subagents.add(sa)
             for h in HALT_SENTINEL.findall(text):
@@ -112,15 +166,24 @@ def classify_session(records: list[dict]) -> tuple[str | None, set[str], list[st
     return skill, subagents, halts
 
 
+def parse_ts(value) -> datetime | None:
+    """Parse an ISO-8601 stamp to an aware UTC datetime. None on anything else."""
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
 def session_bounds(records: list[dict]) -> tuple[datetime | None, datetime | None]:
     first = last = None
     for r in records:
-        ts = r.get("timestamp")
-        if not ts:
-            continue
-        try:
-            dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
-        except (ValueError, AttributeError):
+        dt = parse_ts(r.get("timestamp"))
+        if dt is None:
             continue
         if first is None or dt < first:
             first = dt
@@ -129,19 +192,69 @@ def session_bounds(records: list[dict]) -> tuple[datetime | None, datetime | Non
     return first, last
 
 
-def tally_usage(records: list[dict]) -> dict[str, int]:
+def tally_usage(records: list[dict], start: datetime | None = None,
+                end: datetime | None = None) -> dict[str, int]:
+    """Sum assistant-turn usage. With `start`/`end`, only turns whose timestamp
+    falls inside the closed interval are counted."""
     totals: dict[str, int] = defaultdict(int)
+    for k in USAGE_KEYS:
+        totals[k] = 0
+    totals["turns"] = 0
     for r in records:
         if r.get("type") != "assistant":
             continue
+        if start is not None or end is not None:
+            ts = parse_ts(r.get("timestamp"))
+            if ts is None:
+                continue
+            if start is not None and ts < start:
+                continue
+            if end is not None and ts > end:
+                continue
         usage = (r.get("message") or {}).get("usage") or {}
-        for k in ("input_tokens", "cache_creation_input_tokens",
-                  "cache_read_input_tokens", "output_tokens"):
+        for k in USAGE_KEYS:
             totals[k] += usage.get(k, 0) or 0
         totals["turns"] += 1
     return dict(totals)
 
 
+def phase_usage(sidecar: dict, projects_root: Path | None = None) -> dict | None:
+    """Token usage inside one phase window, per ADR-0009 piece 2.
+
+    Reads the transcript named by `sidecar["session_id"]` and sums assistant-turn
+    usage over records whose `timestamp` falls in
+    `[phase_opened_at, phase_closed_at]`.
+
+    Returns `None` — *unmeasured* — whenever the window cannot be honoured: a
+    schema_version-1 sidecar with no window, a null session id, a transcript
+    swept by `cleanupPeriodDays` or living on another machine, an unparseable or
+    inverted window. Never zero: zero is a measurement, and a phase whose
+    transcript is gone was not measured. Read-only; nothing is written.
+    """
+    if not isinstance(sidecar, dict):
+        return None
+    opened = parse_ts(sidecar.get("phase_opened_at"))
+    closed = parse_ts(sidecar.get("phase_closed_at"))
+    if opened is None or closed is None or closed < opened:
+        return None
+    path = transcript_for_session(sidecar.get("session_id"), projects_root=projects_root)
+    if path is None:
+        return None
+    records = load_session(path)
+    if not records:
+        return None
+    totals = tally_usage(records, start=opened, end=closed)
+    total_tokens = sum(totals.get(k, 0) for k in USAGE_KEYS)
+    return {
+        **totals,
+        "total_tokens": total_tokens,
+        "cost_score": cost_score(totals),
+        "wall_clock_s": (closed - opened).total_seconds(),
+        "session_id": sidecar.get("session_id"),
+        "transcript": str(path),
+    }
+
+
 def cost_score(totals: dict[str, int]) -> int:
     """Same weighting as scripts/audit-token-usage.py: input + 1.25*cache_creation
     + 0.10*cache_read + 5*output. Approximates billable $-weight for ranking."""

package/template/scripts/telemetry/render.py

@@ -61,7 +61,7 @@ def _render_token_economics(lines: list[str], te: dict) -> None:
     _h(lines, 2, "Token economics")
 
     te1 = te.get("te_1_cost_per_change", {})
-    _h(lines, 3, "TE-1 — cost-score per Skill (proxy for per-change cost)")
+    _h(lines, 3, "TE-1 — cost-score per Skill (session-scoped)")
     _p(lines, te1.get("note", ""))
     _table(
         lines,
@@ -71,9 +71,10 @@ def _render_token_economics(lines: list[str], te: dict) -> None:
     )
 
     te2 = te.get("te_2_cache_hit_per_subagent", {})
-    _h(lines, 3, "TE-2 — cache-hit ratio (per Skill, v1 coarse grain)")
+    _h(lines, 3, "TE-2 — cache-hit ratio (per Skill, session-scoped)")
     _p(lines, "ratio = cache_read / (cache_read + cache_creation). Below 0.5 → context "
               "is being rebuilt rather than reused. Above 0.8 → cross-session reuse is healthy.")
+    _p(lines, te2.get("note", ""))
     _table(
         lines,
         ["skill", "turns", "cache_read", "cache_creation", "ratio"],
@@ -93,6 +94,61 @@ def _render_token_economics(lines: list[str], te: dict) -> None:
          for r in te3.get("rows", [])],
     )
 
+    te4 = te.get("te_4_cost_per_phase", {})
+    _h(lines, 3, "TE-4 — cost per phase (sidecar phase window)")
+    _p(lines, _coverage_line(te4, "phase"))
+    _p(lines, te4.get("note", ""))
+    rows4 = te4.get("rows", [])
+    measured4 = [r for r in rows4 if r["measured"]]
+    _table(
+        lines,
+        ["skill", "change", "phase", "tokens", "turns", "wall-clock (h)"],
+        [[r["skill"], r["change"], r["phase_id"] or "-",
+          f"{r['tokens']:,}", r["turns"], r["wall_clock_h"]]
+         for r in measured4[:40]],
+    )
+    unmeasured4 = [r for r in rows4 if not r["measured"]]
+    if unmeasured4:
+        by_reason: dict[str, int] = {}
+        for r in unmeasured4:
+            by_reason[r["unmeasured_reason"] or "unknown"] = by_reason.get(r["unmeasured_reason"] or "unknown", 0) + 1
+        _p(lines, f"**{len(unmeasured4)} unmeasured phase(s)** — counted as nothing, never as zero:")
+        _table(
+            lines,
+            ["reason", "phases"],
+            [[reason, count] for reason, count in sorted(by_reason.items(), key=lambda kv: -kv[1])],
+        )
+
+    te5 = te.get("te_5_cost_per_change", {})
+    _h(lines, 3, "TE-5 — cost per change (sum of measured phases)")
+    _p(lines, _coverage_line(te5, "phase"))
+    _p(lines, te5.get("note", ""))
+    _table(
+        lines,
+        ["change", "tokens", "turns", "wall-clock (h)", "phases measured / emitted", "coverage"],
+        [[r["change"],
+          f"{r['tokens']:,}" if r["tokens"] is not None else "unmeasured",
+          r["turns"] if r["turns"] is not None else "-",
+          r["wall_clock_h"] if r["wall_clock_h"] is not None else "-",
+          f"{r['phases_measured']} / {r['phases_emitted']}",
+          f"{r['coverage_fraction']:.0%}" if r["coverage_fraction"] is not None else "-"]
+         for r in te5.get("rows", [])[:20]],
+    )
+
+
+def _coverage_line(block: dict, unit: str) -> str:
+    emitted = block.get("phases_emitted", 0)
+    measured = block.get("phases_measured", 0)
+    frac = block.get("coverage_fraction")
+    if not emitted:
+        return (f"**Coverage: 0 sidecars in this repo.** No {unit} is measurable — "
+                "either no change has reached a sidecar-emitting terminal state yet, "
+                "or the sidecars pre-date ADR-0009's phase window.")
+    return (f"**Coverage: {measured} of {emitted} emitted sidecars measurable"
+            + (f" ({frac:.0%})" if frac is not None else "") + ".** "
+            "Emitted sidecars come from five Skills only, so this is a subset of the "
+            "change's real cost — read the fraction before reading the totals.")
+
 
 def _render_workflow_shape(lines: list[str], ws: dict) -> None:
     _h(lines, 2, "Workflow shape")
@@ -274,7 +330,7 @@ def _render_contract_drift(lines: list[str], cd: dict) -> None:
 
 def _render_kernel_fit(lines: list[str], kf: dict) -> None:
     _h(lines, 2, "Kernel-fit candidates")
-    _p(lines, "Patterns suggesting the kernel itself (CLAUDE.md, templates, validators, Skill "
+    _p(lines, "Patterns suggesting the kernel itself (KERNEL.md, templates, validators, Skill "
               "flows) may need revision. Each fired pattern is also written as a durable finding "
               "by `/hstack:kernel-fit-scan` at `hstack/kernel-fit/findings/KF-NNNN-*.md`. The "
               "table below is a rollup; the findings are the canonical artifact. See ADR-0004.")
@@ -345,6 +401,15 @@ def watch_items(metrics: dict) -> list[str]:
         if r.get("ratio") is not None and r["ratio"] < 0.5 and r["turns"] > 5:
             items.append(f"Low cache-hit on `{r['skill']}` ({r['ratio']:.0%}) — context is being rebuilt.")
 
+    # TE-4: emitted sidecars the parser could not measure
+    te4 = metrics.get("token_economics", {}).get("te_4_cost_per_phase", {})
+    emitted = te4.get("phases_emitted", 0)
+    measured = te4.get("phases_measured", 0)
+    if emitted and measured < emitted:
+        items.append(f"{emitted - measured} of {emitted} phase sidecars are unmeasured "
+                     "(no phase window, or the session transcript is gone) — TE-4/TE-5 "
+                     "totals are a subset, not a total.")
+
     # QO-2 smells
     smells = metrics.get("quality_outcomes", {}).get("qo_2_severity_resolution_mix", {}).get("high_severity_in_prose_smells", [])
     if smells:

package/template/scripts/telemetry/report.py

@@ -37,7 +37,7 @@ _SCRIPTS = _THIS.parent.parent
 if str(_SCRIPTS) not in sys.path:
     sys.path.insert(0, str(_SCRIPTS))
 
-from telemetry.parsers import frontmatter, commits, transcripts  # noqa: E402
+from telemetry.parsers import frontmatter, commits, transcripts, sidecars  # noqa: E402
 from telemetry.insights import (  # noqa: E402
     token_economics, workflow_shape, quality_outcomes,
     overengineering, contract_drift, kernel_fit,
@@ -59,7 +59,11 @@ def main(argv: list[str] | None = None) -> int:
     hstack_root = repo / "hstack"
     if not hstack_root.is_dir():
         # Permit running against the template repo itself (no hstack/ prefix).
-        if (repo / "specs").is_dir() and (repo / "CLAUDE.md").is_file():
+        # CLAUDE.md is the pre-ADR-0010 kernel name — still accepted so an
+        # un-migrated tree keeps reporting.
+        if (repo / "specs").is_dir() and (
+            (repo / "KERNEL.md").is_file() or (repo / "CLAUDE.md").is_file()
+        ):
             hstack_root = repo
         else:
             print(f"error: no hstack/ directory at {repo}", file=sys.stderr)
@@ -86,9 +90,14 @@ def main(argv: list[str] | None = None) -> int:
     session_rows = transcripts.collect_session_rows([repo], since=since_dt)
     print(f"telemetry: {len(session_rows)} sessions in window", file=sys.stderr)
 
+    # Phase sidecars (ADR-0009). Gitignored and derivative: absent on a fresh
+    # clone, which reports as zero coverage rather than as zero cost.
+    phase_sidecars = sidecars.load_sidecars(hstack_root)
+    print(f"telemetry: {len(phase_sidecars)} phase sidecars", file=sys.stderr)
+
     findings_dir = hstack_root / "kernel-fit" / "findings"
     metrics = {
-        "token_economics": token_economics.compute(session_rows, changes),
+        "token_economics": token_economics.compute(session_rows, changes, phase_sidecars),
         "workflow_shape": workflow_shape.compute(git_commits, changes, session_rows),
         "quality_outcomes": quality_outcomes.compute(git_commits, changes),
         "overengineering": overengineering.compute(git_commits, changes, session_rows, repo),
@@ -112,7 +121,9 @@ def main(argv: list[str] | None = None) -> int:
     # Consumed by the telemetry UI; carries the same derivative-only guarantee.
     json_path = out_path.with_suffix(".json")
     payload = {
-        "schema_version": 1,
+        # 2 — token_economics gains te_4_cost_per_phase / te_5_cost_per_change
+        # (ADR-0009). Additive: every schema_version-1 key keeps its shape.
+        "schema_version": 2,
         "repo": repo.name,
         "generated": date.today().isoformat(),
         "window_days": window_days,
@@ -123,6 +134,7 @@ def main(argv: list[str] | None = None) -> int:
             "module_specs": len(module_specs),
             "commits": len(git_commits),
             "sessions": len(session_rows),
+            "phase_sidecars": len(phase_sidecars),
         },
         "watch_list": render.watch_items(metrics),
         "metrics": metrics,

package/template/scripts/telemetry/run_kernel_fit.py

@@ -49,8 +49,12 @@ def main(argv: list[str] | None = None) -> int:
     repo = args.repo.resolve()
     hstack_root = repo / "hstack"
     if not hstack_root.is_dir():
-        # Permit running against the template repo itself.
-        if (repo / "specs").is_dir() and (repo / "CLAUDE.md").is_file():
+        # Permit running against the template repo itself. CLAUDE.md is the
+        # pre-ADR-0010 kernel name — still accepted so an un-migrated tree
+        # keeps scanning.
+        if (repo / "specs").is_dir() and (
+            (repo / "KERNEL.md").is_file() or (repo / "CLAUDE.md").is_file()
+        ):
             hstack_root = repo
         else:
             print(f"error: no hstack/ directory at {repo}", file=sys.stderr)

package/template/scripts/telemetry/session_id.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Resolve the active Claude Code session id — the one heuristic, in one place.
+
+Per ADR-0009 § Neutral: `/hstack:flag` resolved the session id inline in its own
+prose; the five sidecar-emitting Skills would have duplicated that prose a sixth
+time. They call this module instead.
+
+The heuristic (unchanged from ADR-0005): Claude Code writes one `*.jsonl`
+transcript per session under `~/.claude/projects/<encoded-cwd>/`, where
+`<encoded-cwd>` is the absolute working directory with `/` replaced by `-`. The
+most recently modified file in that directory is the active session; the session
+id is its basename.
+
+Both the heuristic and the transcript layout are harness implementation details,
+not a contract (ADR-0009 § Negative). Every failure mode resolves to
+`session_id: null` — never a guess, never a halt. A null session id means the
+phase reports as *unmeasured*, which is the whole point of the null-not-zero
+rule.
+
+CLI:
+    python3 scripts/telemetry/session_id.py            # JSON on stdout, always exit 0
+    python3 scripts/telemetry/session_id.py --cwd DIR  # resolve for another dir
+
+Output:
+    {"session_id": "062b8fe8-…" | null,
+     "transcript_path": "/Users/…/062b8fe8-….jsonl" | null,
+     "message_count": 1423,
+     "source": "transcript" | "unresolved",
+     "fallback_id": "a3f9c1d2",
+     "now": "2026-08-15T09:12:44Z"}
+
+`now` is the UTC stamp at resolution time, so a Skill opening a phase gets its
+`session_id` and its `phase_opened_at` from one call. `fallback_id` is short
+random hex for callers that need a non-null id anyway (`/hstack:flag` writes
+`fallback-<id>`); sidecar emitters ignore it and write `null`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+PROJECTS_ROOT = Path.home() / ".claude" / "projects"
+
+
+def encoded_cwd(cwd: Path | str | None = None) -> str:
+    """`/Users/jane/code/moso` → `-Users-jane-code-moso`."""
+    p = Path(cwd) if cwd is not None else Path.cwd()
+    return str(p.resolve()).replace("/", "-")
+
+
+def project_dir(cwd: Path | str | None = None, projects_root: Path | None = None) -> Path:
+    root = projects_root or PROJECTS_ROOT
+    return root / encoded_cwd(cwd)
+
+
+def utc_now_iso() -> str:
+    """ISO-8601 UTC, second precision, `Z` suffix — the sidecar timestamp format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def resolve_session(cwd: Path | str | None = None,
+                    projects_root: Path | None = None) -> dict:
+    """Resolve the active session for `cwd`. Never raises; never halts."""
+    out = {
+        "session_id": None,
+        "transcript_path": None,
+        "message_count": 0,
+        "source": "unresolved",
+        "fallback_id": os.urandom(4).hex(),
+        "now": utc_now_iso(),
+    }
+    d = project_dir(cwd, projects_root)
+    try:
+        candidates = [f for f in d.glob("*.jsonl") if f.is_file()]
+    except OSError:
+        return out
+    if not candidates:
+        return out
+    try:
+        newest = max(candidates, key=lambda f: f.stat().st_mtime)
+    except OSError:
+        return out
+    out["session_id"] = newest.stem
+    out["transcript_path"] = str(newest)
+    out["source"] = "transcript"
+    out["message_count"] = _count_lines(newest)
+    return out
+
+
+def _count_lines(path: Path) -> int:
+    try:
+        with open(path, "rb") as fh:
+            return sum(1 for _ in fh)
+    except OSError:
+        return 0
+
+
+def transcript_for_session(session_id: str | None,
+                           projects_root: Path | None = None) -> Path | None:
+    """Locate a transcript by session id, across every project directory.
+
+    The sidecar carries the session id, not the path: a Conductor worktree can be
+    renamed or removed between the write and the read, and the encoded-cwd
+    directory with it. Returns None when no transcript is found — retention
+    sweep, another machine, or a harness layout change. None means *unmeasured*.
+    """
+    if not session_id or not isinstance(session_id, str):
+        return None
+    if session_id.startswith("fallback-"):
+        return None
+    root = projects_root or PROJECTS_ROOT
+    if not root.is_dir():
+        return None
+    for d in sorted(root.iterdir()):
+        if not d.is_dir():
+            continue
+        candidate = d / f"{session_id}.jsonl"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Resolve the active Claude Code session id.")
+    parser.add_argument("--cwd", type=Path, default=None,
+                        help="Directory to resolve for (default: current working directory).")
+    args = parser.parse_args(argv)
+    print(json.dumps(resolve_session(args.cwd), indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())