stacktrace-cli 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

{stacktrace_cli → stacktrace}/__init__.py

@@ -2,9 +2,13 @@
 
 import logging as _logging
 
-__version__ = "0.9.0"
+__version__ = "0.11.0"
 
 # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
 # logged in any other process would reach Python's last-resort handler and
 # print onto the user's terminal.
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())
+
+from stacktrace.sdk import ObservationClient
+
+__all__ = ["ObservationClient", "__version__"]

stacktrace/__main__.py

@@ -0,0 +1,14 @@
+"""Entry point shared by the ``stacktrace`` command and ``python -m stacktrace``.
+
+The distribution's console script resolves to the Click group in
+``stacktrace.cli`` through this module.
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    main()

{stacktrace_cli → stacktrace}/analysis.py

@@ -26,19 +26,19 @@ from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any, Final
 
-from stacktrace_cli.correlate.orchestrate import Acquired, acquire_correlated_view
-from stacktrace_cli.correlate.project_map import parse_mapping
-from stacktrace_cli.correlate.record import CorrelatedSession, CorrelatedView, Coverage
-from stacktrace_cli.detector.cache import VerdictCache
-from stacktrace_cli.detector.history import DriftHistory
-from stacktrace_cli.detector.run import (
+from stacktrace.correlate.orchestrate import Acquired, acquire_correlated_view
+from stacktrace.correlate.project_map import parse_mapping
+from stacktrace.correlate.record import CorrelatedSession, CorrelatedView, Coverage
+from stacktrace.detector.cache import VerdictCache
+from stacktrace.detector.history import DriftHistory
+from stacktrace.detector.run import (
     DEFAULT_BUDGET,
     DEFAULT_SAMPLE_BUDGET,
     NO_ANALYZER,
     DetectorRun,
     run_detector,
 )
-from stacktrace_cli.sessions.access import SessionView, collect_sessions
+from stacktrace.sessions.access import SessionView, collect_sessions
 
 
 @dataclass(frozen=True)

{stacktrace_cli → stacktrace}/cli.py

@@ -33,6 +33,7 @@ from .detector.history import DriftHistory, default_history_path
 from .detector.render import render_json as render_detections_json
 from .detector.render import render_text as render_detections_text
 from .detector.run import DEFAULT_BUDGET, DEFAULT_SAMPLE_BUDGET
+from .gateway.cli import guard as guard_cmd
 from .monitor.server import serve
 from .options import analyzer_option, resolve_analyzer
 from .remote.cli import main as remote_cmd
@@ -637,5 +638,6 @@ main.add_command(detect)
 main.add_command(monitor)
 main.add_command(daemon_cmd, "daemon")
 main.add_command(findings)
+main.add_command(guard_cmd, "guard")
 main.add_command(telemetry_cmd, "telemetry")
 main.add_command(webhook_cmd, "webhook")

{stacktrace_cli → stacktrace}/cloud/__init__.py

@@ -2,8 +2,9 @@
 
 A cloud environment's setup script runs once, as root, before the filesystem is
 snapshotted and reused by every later session. What a session needs that is not
-the CLI itself — the per-session boot hook and the asset identity — has to be
-laid down there so it lands inside the snapshot.
+the CLI itself — the per-session boot hook, the asset identity, and how the hook
+updates the CLI to the latest release (ADR-0123) — has to be laid down there so
+it lands inside the snapshot.
 
 Rather than paste that into the setup-script box, a setup script installs the
 CLI and runs this:
@@ -38,6 +39,16 @@ from __future__ import annotations
 
 import os
 import sys
+
+
+def in_cloud_session() -> bool:
+    """Whether this process runs inside a Claude Code cloud session, which
+    sets `CLAUDE_CODE_REMOTE=true` and never sets it locally (ADR-0043). The
+    daemon reads it from the environment the boot hook starts it in. A cloud
+    machine runs one session, for the person who started it (ADR-0121)."""
+    return os.environ.get("CLAUDE_CODE_REMOTE") == "true"
+
+
 from pathlib import Path
 
 

{stacktrace_cli → stacktrace}/cloud/setup.sh

@@ -2,7 +2,7 @@
 # Lay down everything a Claude Code cloud session needs, at environment setup.
 #
 # Run once by the environment's setup script, as root, before the filesystem is
-# snapshotted. Two things, both of which must be inside that snapshot because
+# snapshotted. Three things, all of which must be inside that snapshot because
 # the setup script does not run again for later sessions:
 #
 #   1. /usr/local/bin/stacktrace-boot.sh — the per-session hook that configures
@@ -14,6 +14,11 @@
 #      asset-display-prefix makes the fleet label `cloud (<id>)` rather than
 #      the image's hostname (`vm`), which is the same on every box. Label
 #      only: the key above is what identifies the asset.
+#   3. /usr/local/lib/stacktrace/boot-worker.py, which the hook hands the
+#      update and the daemon start to, and /usr/local/etc/stacktrace/update.env,
+#      the uv and the directories the installer used, so the client is brought
+#      up to the latest release first (ADR-0123). update.env is not written
+#      when STACKTRACE_VERSION pins a version, or when uv is not on PATH.
 #
 # The telemetry install id is deliberately NOT seeded here. Seeding it would
 # make `read_install_id()` non-None before any event runs, so the one-time
@@ -38,8 +43,8 @@
 # home, because that home does not exist until this run creates it.
 #
 # Options (all optional):
-#   --asset-id VALUE   use this asset id instead of minting one; also taken
-#                      from STACKTRACE_ASSET_EXTERNAL_ID in the environment
+#   --asset-id VALUE   use this asset id instead of minting a bare UUID; also
+#                      taken from STACKTRACE_ASSET_EXTERNAL_ID in the environment
 #   --root DIR         treat DIR as / (for testing)
 #
 # The remote token and API URL, and the Slack webhook URL, are read by the boot
@@ -62,7 +67,7 @@ while [ $# -gt 0 ]; do
     # the loop spins forever — a malformed invocation would hang setup.
     --asset-id) [ $# -ge 2 ] || { echo "✗ --asset-id needs a value" >&2; exit 2; }; ASSET_ID="$2"; shift 2 ;;
     --root) [ $# -ge 2 ] || { echo "✗ --root needs a value" >&2; exit 2; }; ROOT="$2"; shift 2 ;;
-    -h|--help) sed -n '2,52p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -h|--help) sed -n '2,57p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) echo "✗ unknown argument: $1" >&2; exit 2 ;;
   esac
 done
@@ -82,7 +87,9 @@ _uuid() {
 }
 
 DISPLAY_PREFIX="cloud"
-[ -n "$ASSET_ID" ] || ASSET_ID="cloud-$(_uuid)"
+# A bare UUID, like every key `remote/identity.py` mints (ADR-0105). The kind of
+# box is the label's business (asset-display-prefix below), not the key's.
+[ -n "$ASSET_ID" ] || ASSET_ID="$(_uuid)"
 # remote/identity.py:_is_identifier rejects whitespace, non-printable
 # characters, and anything over 255 characters. A value this accepts but the
 # runtime rejects is worse than no file: every session reads it, rejects it,
@@ -103,9 +110,18 @@ fi
 # command points at a file that does not exist and the daemon never starts —
 # a silent total failure worse than a setup that stops and says so.
 BOOT="${ROOT}/usr/local/bin/stacktrace-boot.sh"
-mkdir -p "$(dirname "$BOOT")" || { echo "✗ cannot create $(dirname "$BOOT")" >&2; exit 1; }
-cat > "$BOOT" <<'BOOTSCRIPT' || { echo "✗ cannot write $BOOT" >&2; exit 1; }
-#!/usr/bin/env bash
+# The worker the hook hands the update and the daemon start to, and where setup
+# records how that worker updates the client (ADR-0123). Both are named in the
+# hook itself, so the hook never guesses them.
+WORKER="${ROOT}/usr/local/lib/stacktrace/boot-worker.py"
+UPDATE_ENV="${ROOT}/usr/local/etc/stacktrace/update.env"
+mkdir -p "$(dirname "$BOOT")" "$(dirname "$WORKER")" \
+  || { echo "✗ cannot create $(dirname "$BOOT") or $(dirname "$WORKER")" >&2; exit 1; }
+{
+  printf '#!/usr/bin/env bash\n'
+  printf 'WORKER=%q\n' "$WORKER"
+  printf 'UPDATE_ENV=%q\n' "$UPDATE_ENV"
+  cat <<'BOOTSCRIPT'
 # Configure the remote and start the daemon for this cloud session. No-op
 # anywhere else. The asset id is already on disk from setup, so this does not
 # touch it: it only configures the token and starts the daemon, which resolves
@@ -148,20 +164,186 @@ if [ -n "${STACKTRACE_SLACK_WEBHOOK_URL:-}" ]; then
     --secret "${STACKTRACE_WEBHOOK_SECRET:-}" >/dev/null 2>&1 || true
 fi
 
+# The snapshot holds the client this environment's setup installed, and setup
+# never runs again, so the worker brings the client up to the latest release
+# before it starts the daemon (ADR-0123). It runs detached, so the session never
+# waits on the network, and one worker at a time decides, so no two overlapping
+# hooks can replace the client's files under a daemon the other started.
+# Without python3 the hook starts the daemon as it always has, with no update.
+#
 # Streams redirected because own_std_streams only re-points fd 1/2 on log
 # rollover; without this the daemon inherits the hook's pipe to Claude Code.
 # --no-reasoning is explicit, not just `run`'s own default (ADR-0081): this
 # hook never provisions TYPESAFE_API_KEY itself, but a cloud VM's ambient
 # environment is not something this script controls or can audit ahead of
 # time, and this surface has nobody present to notice if that changed.
-if ! stacktrace daemon status 2>/dev/null | grep -q '^running: yes'; then
+if command -v python3 >/dev/null 2>&1 && [ -r "$WORKER" ]; then
+  if command -v setsid >/dev/null 2>&1; then
+    setsid nohup python3 "$WORKER" "$STATE" "$UPDATE_ENV" </dev/null >/dev/null 2>&1 &
+  else
+    nohup python3 "$WORKER" "$STATE" "$UPDATE_ENV" </dev/null >/dev/null 2>&1 &
+  fi
+elif ! stacktrace daemon status 2>/dev/null | grep -q '^running: yes'; then
   setsid nohup stacktrace daemon run --no-reasoning </dev/null >>"$STATE/daemon.log" 2>&1 &
 fi
 exit 0
 BOOTSCRIPT
+} > "$BOOT" || { echo "✗ cannot write $BOOT" >&2; exit 1; }
 chmod 755 "$BOOT" || { echo "✗ cannot chmod $BOOT" >&2; exit 1; }
 echo "✓ $BOOT"
 
+cat > "$WORKER" <<'WORKERSCRIPT' || { echo "✗ cannot write $WORKER" >&2; exit 1; }
+"""Bring a cloud session's client up to the latest release, then start its
+daemon (ADR-0123). Run detached by stacktrace-boot.sh, with the state
+directory and the file setup recorded the install in.
+
+One worker at a time holds `boot.lock`, from its own `daemon status` check
+until the daemon it starts answers. So a worker never replaces the client's
+files while a daemon runs or is starting: a second hook's worker waits, checks
+again, and finds the daemon up.
+"""
+
+import fcntl
+import os
+import pwd
+import shlex
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+
+STATE, UPDATE_ENV = sys.argv[1], sys.argv[2]
+#: How long an update may take before the installed client runs instead.
+UPDATE_SECONDS = 120
+#: How long the lock waits for the daemon this worker started to answer.
+START_SECONDS = 30
+
+
+def note(text):
+    with open(os.path.join(STATE, "update.log"), "a", encoding="utf-8") as log:
+        log.write(f"{datetime.now(timezone.utc):%Y-%m-%dT%H:%M:%SZ} {text}\n")
+
+
+def running():
+    """What `daemon status` says: yes, no, unresponsive, or "" for no answer."""
+    try:
+        status = subprocess.run(
+            ["stacktrace", "daemon", "status"], capture_output=True, text=True, timeout=30
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    for line in status.splitlines():
+        if line.startswith("running: "):
+            return line[len("running: "):].strip()
+    return ""
+
+
+def recorded():
+    """The uv and the UV_* directories setup wrote, as `KEY=value` lines."""
+    try:
+        lines = open(UPDATE_ENV, encoding="utf-8").read().splitlines()
+    except OSError:
+        return {}
+    values = {}
+    for line in lines:
+        words = shlex.split(line)
+        if words[:1] == ["export"]:
+            words = words[1:]
+        if len(words) == 1 and "=" in words[0]:
+            key, value = words[0].split("=", 1)
+            values[key] = value
+    return values
+
+
+def update():
+    """Upgrade the tool install setup recorded, as a user who can write it;
+    else say why not. No file: the client is pinned, or setup found no uv."""
+    values = recorded()
+    if not values:
+        return
+    uv = values.get("STACKTRACE_UV", "")
+    directories = [values[key] for key in ("UV_TOOL_DIR", "UV_TOOL_BIN_DIR") if values.get(key)]
+    if not (uv and os.access(uv, os.X_OK)) or not all(os.access(d, os.W_OK) for d in directories):
+        user = pwd.getpwuid(os.getuid()).pw_name
+        note(
+            f"not updating: {user} cannot run uv or write the install; "
+            "rebuild the environment to update the client"
+        )
+        return
+    environment = {**os.environ, **{k: v for k, v in values.items() if k.startswith("UV_")}}
+    with open(os.path.join(STATE, "update.log"), "a", encoding="utf-8") as log:
+        try:
+            subprocess.run(
+                [uv, "tool", "upgrade", "stacktrace-cli"],
+                env=environment,
+                stdin=subprocess.DEVNULL,
+                stdout=log,
+                stderr=subprocess.STDOUT,
+                timeout=UPDATE_SECONDS,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as error:
+            note(f"update stopped: {type(error).__name__}; the installed client runs")
+
+
+def main():
+    lock = os.open(os.path.join(STATE, "boot.lock"), os.O_CREAT | os.O_RDWR, 0o600)
+    fcntl.flock(lock, fcntl.LOCK_EX)
+    answer = running()
+    if answer == "yes":
+        return
+    # Only a status of no daemon lets the update run: `unresponsive` is a
+    # daemon holding its lock that has not answered yet, and an error or no
+    # answer says nothing. Either may be a live client.
+    if answer == "no":
+        update()
+    else:
+        note(f"not updating: daemon status said {answer or 'nothing'}, not that no daemon runs")
+    with open(os.path.join(STATE, "daemon.log"), "a", encoding="utf-8") as out:
+        subprocess.Popen(
+            ["stacktrace", "daemon", "run", "--no-reasoning"],
+            stdin=subprocess.DEVNULL,
+            stdout=out,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+    deadline = time.monotonic() + START_SECONDS
+    while time.monotonic() < deadline and running() != "yes":
+        time.sleep(0.5)
+
+
+if __name__ == "__main__":
+    main()
+WORKERSCRIPT
+chmod 644 "$WORKER" || { echo "✗ cannot chmod $WORKER" >&2; exit 1; }
+echo "✓ $WORKER"
+
+# ---- how the boot hook keeps the client current ----------------------------
+# The uv and the directories the installer used (remote-install.sh exports
+# them before running this), so the boot hook updates the same tool install
+# (ADR-0123). Nothing is recorded when STACKTRACE_VERSION pins a version, or
+# when uv is not found: sessions then run the client this setup installed.
+# Not fatal: without it a session runs the installed client, as before.
+UV_BIN="$(command -v uv 2>/dev/null || true)"
+if [ -n "$UV_BIN" ] && { [ -z "${STACKTRACE_VERSION:-}" ] || [ "$STACKTRACE_VERSION" = "latest" ]; }; then
+  if mkdir -p "$(dirname "$UPDATE_ENV")" 2>/dev/null && {
+    printf 'STACKTRACE_UV=%q\n' "$UV_BIN"
+    for variable in UV_TOOL_DIR UV_TOOL_BIN_DIR UV_PYTHON_INSTALL_DIR UV_PYTHON_PREFERENCE; do
+      if [ -n "${!variable:-}" ]; then
+        printf 'export %s=%q\n' "$variable" "${!variable}"
+      fi
+    done
+  } >"$UPDATE_ENV" 2>/dev/null; then
+    chmod 644 "$UPDATE_ENV" 2>/dev/null || true
+    echo "✓ $UPDATE_ENV"
+  else
+    echo "! cannot write $UPDATE_ENV — sessions run the installed client" >&2
+  fi
+else
+  rm -f "$UPDATE_ENV" 2>/dev/null || true
+  echo "· the client is pinned or uv is not on PATH — sessions run the installed client"
+fi
+
 # ---- seed every home -----------------------------------------------------
 # Every existing home is seeded because the future session user is unknown, so a
 # home that exists but cannot be seeded is a failure, not a skip: the session

stacktrace/core/__init__.py

@@ -0,0 +1,27 @@
+"""Supported domain API for Stacktrace hosts, including Fleet.
+
+Importing this module starts no services and configures no remote clients.
+The distribution is ``stacktrace-cli``; its CLI and daemon are optional callers.
+"""
+
+from stacktrace.core.observations import (
+    Decision,
+    DecisionRequest,
+    DecisionResponse,
+    Identifier,
+    Observation,
+    ObserveRequest,
+    StructuralPayload,
+    project_workflow,
+)
+
+__all__ = [
+    "Decision",
+    "DecisionRequest",
+    "DecisionResponse",
+    "Identifier",
+    "Observation",
+    "ObserveRequest",
+    "StructuralPayload",
+    "project_workflow",
+]

stacktrace/core/observations.py

@@ -0,0 +1,222 @@
+"""Shared, storage-independent observation contract and evidence projection.
+
+Stacktrace owns the envelope. Adapters map external conventions into optional
+context and bounded JSON payloads. Capture profiles control content export.
+"""
+
+import json
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Any, Literal, TypedDict
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, JsonValue
+
+from stacktrace.detector.secrets import contains_credential_shape, is_secret_key_name
+
+
+def _reject_credential_shaped(value: str) -> str:
+    """Reject known credential shapes, including namespaced and glued values."""
+    if contains_credential_shape(value):
+        raise ValueError("identifier fields must not contain credential-shaped values")
+    return value
+
+
+Identifier = Annotated[
+    str,
+    Field(pattern=r"^[A-Za-z0-9_:-]{1,96}$"),
+    AfterValidator(_reject_credential_shaped),
+]
+
+
+def _reject_calendar_invalid(value: str) -> str:
+    """The pattern alone accepts shapes like `2026-99-99T99:99:99Z`; `project_workflow`
+    later feeds this to `datetime.fromisoformat`, which would raise on such a value."""
+    datetime.fromisoformat(value)
+    return value
+
+
+Timestamp = Annotated[
+    str,
+    Field(pattern=r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$"),
+    AfterValidator(_reject_calendar_invalid),
+]
+
+
+class ClosedModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, allow_inf_nan=False)
+
+
+class EventContext(ClosedModel):
+    agent_id: Identifier | None = None
+    # Labels are scoped to the authenticated source, never global session keys.
+    session_id: Identifier | None = None
+    correlation_id: Identifier | None = None
+    parent_event_id: Identifier | None = None
+
+
+Label = Annotated[
+    str,
+    Field(pattern=r"^[A-Za-z0-9_.:/-]{1,128}$"),
+    AfterValidator(_reject_credential_shaped),
+]
+
+
+class Decision(StrEnum):
+    """Policy decision values shared by Python callers and the JSON contract."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    APPROVAL_REQUIRED = "approval_required"
+    UNDECIDED = "undecided"
+
+
+class StructuralPayload(ClosedModel):
+    """Optional conventions eligible for structural-only export, not required fields."""
+
+    tool_name: Label | None = None
+    tool_call_id: Identifier | None = None
+    target: Label | None = None
+    operation: Label | None = None
+    duration_ms: Annotated[float, Field(ge=0)] | None = None
+    outcome: Literal["completed", "failed", "blocked", "unknown"] | None = None
+    decision: Decision | None = Field(default=None, strict=False)
+    decision_id: Identifier | None = None
+    policy_version: Identifier | None = None
+    provenance: Literal["observed", "asserted", "inferred", "unknown"] | None = None
+
+
+def _validate_payload(value: dict[str, JsonValue]) -> dict[str, JsonValue]:
+    """Bound arbitrary JSON and reject known secrets; this does not anonymize content."""
+    pending: list[tuple[JsonValue, int]] = [(value, 0)]
+    count = 0
+    while pending:
+        item, depth = pending.pop()
+        count += 1
+        if depth > 8 or count > 2048:
+            raise ValueError("payload exceeds structural limits")
+        if isinstance(item, dict):
+            for key, child in item.items():
+                if len(key) > 128 or is_secret_key_name(key):
+                    raise ValueError("payload contains a prohibited key")
+                _reject_credential_shaped(key)
+                pending.append((child, depth + 1))
+        elif isinstance(item, list):
+            pending.extend((child, depth + 1) for child in item)
+        elif isinstance(item, str):
+            _reject_credential_shaped(item)
+    try:
+        encoded = json.dumps(value, ensure_ascii=True, allow_nan=False, separators=(",", ":"))
+    except (ValueError, OverflowError) as exc:
+        raise ValueError("payload must contain finite JSON values") from exc
+    if len(encoded) > 16384:
+        raise ValueError("payload exceeds 16 KiB")
+    return value
+
+
+class Observation(ClosedModel):
+    version: Literal[1]
+    event_id: Identifier
+    type: Label
+    timestamp: Timestamp
+    context: EventContext | None = None
+    payload: Annotated[dict[str, JsonValue], AfterValidator(_validate_payload)] | None = None
+
+    @property
+    def workflow_id(self) -> str:
+        # No invented workflow/session correlation when the producer supplies none.
+        return (self.context.correlation_id if self.context else None) or self.event_id
+
+
+class ObserveRequest(ClosedModel):
+    mode: Literal["observe"]
+    source_id: Identifier
+    events: Annotated[list[Observation], Field(min_length=1, max_length=64)]
+
+
+class DecisionRequest(ClosedModel):
+    """Contract for future decide mode; the current service rejects this mode."""
+
+    mode: Literal["decide"]
+    source_id: Identifier
+    timeout_ms: Annotated[int, Field(ge=1, le=60000)]
+    event: Observation
+    context_events: Annotated[list[Observation], Field(max_length=64)] = Field(default_factory=list)
+
+
+class DecisionResponse(ClosedModel):
+    event_id: Identifier
+    decision_id: Identifier
+    decision: Decision = Field(strict=False)
+    policy_version: Identifier
+    matched_rules: Annotated[list[Identifier], Field(max_length=64)] = Field(default_factory=list)
+    reason: Annotated[str, Field(max_length=1024)] | None = None
+
+
+class WorkflowProjection(TypedDict):
+    events: list[dict[str, Any]]
+    missing_parents: list[str]
+    coverage: str
+
+
+def _view(event: Observation) -> dict[str, Any]:
+    """Derived UI fields do not widen the event's wire envelope."""
+    payload = event.payload or {}
+    context = event.context
+    decision = payload.get("decision")
+    outcome = payload.get("outcome") if event.type == "tool.result" else None
+    provenance = payload.get("provenance")
+    return {
+        **event.model_dump(mode="json"),
+        "actor": (context.agent_id if context else None) or "unknown",
+        "target": next(
+            (payload[key] for key in ("tool_name", "target") if isinstance(payload.get(key), str)),
+            "unknown",
+        ),
+        "action": event.type,
+        "occurred_at": event.timestamp,
+        "parent_event_id": context.parent_event_id if context else None,
+        "decision": decision
+        if isinstance(decision, str) and decision in {value.value for value in Decision}
+        else "not_reported",
+        "outcome": outcome
+        if isinstance(outcome, str) and outcome in {"completed", "failed", "blocked"}
+        else "unknown",
+        "provenance": provenance
+        if isinstance(provenance, str) and provenance in {"observed", "asserted", "inferred"}
+        else "unknown",
+    }
+
+
+def project_workflow(events: list[Observation]) -> WorkflowProjection:
+    """Timestamp ordering is presentation, not causality or delivery completeness.
+
+    `events` must come from one authenticated source. `Observation` carries no
+    `source_id` -- by design (ADR-0120), source identity lives at the request/
+    authenticated-API boundary (`ObserveRequest.source_id`), never inside the
+    event envelope -- so this function has no way to tell two sources' events
+    apart if a caller merges them before calling it. Cross-source stitching is
+    explicitly deferred (docs/specs/production-agent-observability.md); callers
+    must partition by source before projecting, the same way every caller in
+    this repository already does (one `ObserveRequest`'s `events` per call).
+    """
+    ordered = sorted(events, key=lambda e: (datetime.fromisoformat(e.timestamp), e.event_id))
+    # Scoped per workflow_id: an event_id from one workflow must not resolve a
+    # parent_event_id in an unrelated one, matching "parent references resolve
+    # only within that source/workflow" (docs/specs/production-agent-observability.md).
+    ids_by_workflow: dict[str, set[str]] = {}
+    for event in events:
+        ids_by_workflow.setdefault(event.workflow_id, set()).add(event.event_id)
+    missing = sorted(
+        {
+            e.context.parent_event_id
+            for e in events
+            if e.context
+            and e.context.parent_event_id
+            and e.context.parent_event_id not in ids_by_workflow.get(e.workflow_id, set())
+        }
+    )
+    return {
+        "events": [_view(event) for event in ordered],
+        "missing_parents": missing,
+        "coverage": "partial" if missing else "reported_only",
+    }

{stacktrace_cli → stacktrace}/correlate/acquire.py

@@ -36,9 +36,10 @@ from importlib.metadata import (
 from pathlib import Path
 from typing import Any
 
-from stacktrace_cli.correlate.composition import (
+from stacktrace.correlate.composition import (
     Advisory,
     Composition,
+    composable,
     composition_from_bom,
     reject_malformed_shape,
     root_property,
@@ -234,8 +235,13 @@ def build_bom(
 
     Returns None rather than raising when nothing was produced: a machine can run
     one agent kind and not another, which is a fact about the machine rather than
-    a failure to look.
+    a failure to look. A kind OpenACA does not know is the same answer for the
+    same reason -- sessions can come from an agent whose setup OpenACA cannot
+    describe yet, and those sessions resolve as having no composition rather than
+    failing every other kind's run.
     """
+    if not composable(agent_kind):
+        return None
     with tempfile.TemporaryDirectory() as scratch:
         directory = Path(scratch)
         argv = [