execweave 0.8.11__tar.gz → 0.8.13__tar.gz

{execweave-0.8.11 → execweave-0.8.13}/.github/workflows/ci.yml

@@ -133,7 +133,10 @@ jobs:
       - name: Ruff
         run: ruff check .
       - name: Tests
-        run: pytest -q
+        run: pytest -q --junitxml=pytest-results.xml
+      - name: Annotate pytest failures
+        if: failure() && hashFiles('pytest-results.xml') != ''
+        run: python scripts/annotate_pytest_failures.py pytest-results.xml
       - name: Claude hook command smoke
         run: python scripts/check_claude_hook.py
       - name: Claude run-bound semantic and correlation smoke

{execweave-0.8.11 → execweave-0.8.13}/.github/workflows/provider-capability-stage-integrity.yml

@@ -147,11 +147,62 @@ jobs:
               esac
             done < <(git diff --name-only "$BASELINE_REF...HEAD" -- tests)
           fi
+          if [[ "$HEAD_REF" == "test/live-dashboard-acceptance" ]]; then
+            while IFS= read -r path; do
+              case "$path" in
+                tests/test_command.py)
+                  args+=(--allow-test-change "$path=acceptance branch isolates the historical Windows shim fallback from installed Cursor desktop candidates; native desktop preference and custom-install contracts remain separate and existing test node IDs are unchanged")
+                  ;;
+                tests/test_codex_adapter.py)
+                  args+=(--allow-test-change "$path=Codex now documents Interrupt as a first-class hook with a bounded handler contract; the existing config test node ID is retained and now asserts the current official event and timeout semantics")
+                  ;;
+                tests/test_codex_hook_lifecycle.py)
+                  args+=(--allow-test-change "$path=Codex now documents Interrupt as a first-class lifecycle event; the historical test node ID is retained while its assertion is corrected to the current official contract")
+                  ;;
+                tests/test_v069_dashboard_release.py)
+                  args+=(--allow-test-change "$path=README policy is now stable product documentation instead of release notes; the historical test node IDs are retained while assertions require no hard-coded release tags and preserve dashboard/conversation/license anchors")
+                  ;;
+                tests/test_graph_clear_focus_e2e.py|tests/test_graph_edge_routing_e2e.py|tests/test_graph_node_sizing_e2e.py|tests/test_tool_traffic_e2e.py)
+                  args+=(--allow-test-change "$path=existing browser assertions are unchanged; the module-level viewer_e2e marker makes the dedicated three-OS browser workflow collect tests that were previously omitted")
+                  ;;
+                tests/test_graph_lane_separation_e2e.py)
+                  args+=(--allow-test-change "$path=layout acceptance separates endpoint projection from lane geometry using loopback fixtures and replaces obsolete fixed canvas coordinates with semantic lane/band invariants; historical test node IDs remain unchanged")
+                  ;;
+                tests/test_http_proxy.py)
+                  args+=(--allow-test-change "$path=NEW-005 adds native streaming-order regressions for content-length and chunked responses; existing test assertions and node IDs are unchanged")
+                  ;;
+                tests/test_conversation_access.py)
+                  args+=(--allow-test-change "$path=the historical live conversation-access test now requires bounded authenticated polling with AbortController cleanup at finished state; the test node ID and auth/path-boundary assertions remain unchanged")
+                  ;;
+                tests/test_semantic.py)
+                  args+=(--allow-test-change "$path=NEW-006 adds contradictory and future PID identity regressions through merge and graph materialization; existing test assertions and node IDs are unchanged")
+                  ;;
+                tests/test_live_auth.py)
+                  args+=(--allow-test-change "$path=acceptance branch adds the native client-reset regression proving expected Windows disconnects are suppressed without hiding unexpected server errors")
+                  ;;
+                tests/test_process_tree_layout.py)
+                  args+=(--allow-test-change "$path=acceptance branch replaces obsolete fixed layout coordinates with semantic lane and ordering assertions while retaining the historical test node IDs")
+                  ;;
+                tests/test_external_endpoints_all_providers.py)
+                  args+=(--allow-test-change "$path=loopback endpoint presentation intentionally changed from individual raw nodes to one provider-neutral Local endpoints cluster while External behavior remains; historical test node IDs are retained and raw endpoint evidence is unchanged")
+                  ;;
+                tests/test_viewer_projection.py)
+                  args+=(--allow-test-change "$path=approved provider-neutral endpoint semantics retire the old four-endpoint threshold and per-process loopback cluster shape: every loopback endpoint now folds into one Local endpoints node while source edges, chronology, expansion evidence, and historical test node IDs are retained")
+                  ;;
+                tests/test_dashboard_information_architecture.py)
+                  args+=(--allow-test-change "$path=approved orphan-file presentation now folds degree-zero file and directory nodes into the expandable Files / directories viewer cluster; the historical test node ID remains and the assertion now requires the original notes.txt evidence in cluster expansion")
+                  ;;
+                tests/test_viewer_agent_isolation_e2e.py)
+                  args+=(--allow-test-change "$path=live conversation ownership now reads the raw observed graph before viewer-only endpoint, request, and orphan collapse; historical test IDs and conversation completeness assertions remain unchanged and only the live-index fixture injection seam follows _raw_graph_locked")
+                  ;;
+              esac
+            done < <(git diff --name-only "$BASELINE_REF...HEAD" -- tests)
+          fi
           if [[ "$HEAD_REF" == "audit/remaining-providers-v0.8.7" ]]; then
             args+=(--allow-retired-provider "gemini=Gemini integration was retired and replaced by the AGY/Antigravity provider; only Gemini-owned test IDs and files may disappear")
             while IFS= read -r path; do
               case "$path" in
-                tests/fixtures/hooks/manifest.json|tests/test_agent_bootstrap.py|tests/test_agent_topology_evidence.py|tests/test_agent_trace_viewer_visibility.py|tests/test_antigravity_agent_collaboration.py|tests/test_antigravity_child_transcript_tools.py|tests/test_antigravity_cursor_launch.py|tests/test_antigravity_identity_topology.py|tests/test_antigravity_invocation_archive.py|tests/test_antigravity_official_contract.py|tests/test_antigravity_subagent_transcript_linkage.py|tests/test_antigravity_trace_capability_cli.py|tests/test_claude_adapter.py|tests/test_codex_real_multi_agent_conversation.py|tests/test_collector.py|tests/test_command.py|tests/test_conversation_access.py|tests/test_conversation_agent_isolation.py|tests/test_conversation_identity_merge.py|tests/test_conversation_provider_parity.py|tests/test_cross_provider_agent_trace.py|tests/test_cursor_adapter.py|tests/test_dashboard_information_architecture.py|tests/test_external_endpoints_all_providers.py|tests/test_hook_fixture_corpus.py|tests/test_provider_capability.py|tests/test_provider_conversation_evidence.py|tests/test_provider_lifecycle.py|tests/test_v064_live_auto_integrations.py)
+                tests/fixtures/hooks/manifest.json|tests/test_agent_bootstrap.py|tests/test_agent_topology_evidence.py|tests/test_agent_trace_viewer_visibility.py|tests/test_antigravity_agent_collaboration.py|tests/test_antigravity_child_transcript_tools.py|tests/test_antigravity_cursor_launch.py|tests/test_antigravity_identity_topology.py|tests/test_antigravity_invocation_archive.py|tests/test_antigravity_official_contract.py|tests/test_antigravity_subagent_transcript_linkage.py|tests/test_antigravity_trace_capability_cli.py|tests/test_claude_adapter.py|tests/test_codex_real_multi_agent_conversation.py|tests/test_collector.py|tests/test_command.py|tests/test_conversation_access.py|tests/test_conversation_agent_isolation.py|tests/test_conversation_identity_merge.py|tests/test_cross_provider_agent_trace.py|tests/test_cursor_adapter.py|tests/test_dashboard_information_architecture.py|tests/test_external_endpoints_all_providers.py|tests/test_hook_fixture_corpus.py|tests/test_provider_capability.py|tests/test_provider_conversation_evidence.py|tests/test_provider_lifecycle.py|tests/test_v064_live_auto_integrations.py)
                   args+=(--allow-test-change "$path=Gemini provider retirement and provider-neutral AGY/dashboard contract updates are intentional on this branch; existing test node IDs remain stable where the provider is still supported")
                   ;;
               esac

{execweave-0.8.11 → execweave-0.8.13}/.github/workflows/provider-dashboard-contract.yml

@@ -39,6 +39,7 @@ jobs:
           tests/test_provider_conversation_evidence.py
           tests/test_provider_conversation_history_integrity.py
           tests/test_external_endpoints_all_providers.py
+          tests/test_provider_neutral_viewer_semantics.py
           tests/test_graph.py
           tests/test_antigravity_field_run_regressions.py
           tests/test_antigravity_subagent_transcript_linkage.py
@@ -145,5 +146,6 @@ jobs:
           python -m pytest -q
           tests/test_provider_dashboard_contract.py
           ${{ matrix.tests }}
+          tests/test_provider_neutral_viewer_semantics.py
       - name: Check dashboard JavaScript syntax
         run: python -m pytest -q tests/test_live_dashboard_js.py tests/test_live_dashboard.py

execweave-0.8.13/.github/workflows/viewer-agent-isolation.yml

@@ -0,0 +1,89 @@
+name: Viewer Agent Isolation
+
+# The release gate opens the actual dashboard in Chromium. It reads the visible
+# root/subagent/non-agent inspectors, compares live with viewer.html, and archives
+# screenshots plus the rendered live.html for a human visual pass.
+on:
+  pull_request:
+  push:
+    branches: [main, test/live-dashboard-acceptance]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  viewers:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: python -m pip install -e ".[dev,e2e]"
+
+      - name: Install Chromium
+        run: python -m playwright install --with-deps chromium
+
+      - name: Read live and viewer.html in a browser (Linux)
+        if: runner.os == 'Linux'
+        env:
+          EXECWEAVE_E2E_REQUIRED: "1"
+          EXECWEAVE_VISUAL_ARTIFACT_DIR: visual-artifacts
+        run: xvfb-run -a python -m pytest -m viewer_e2e -v --junitxml=viewer-pytest-results.xml
+
+      - name: Read live and viewer.html in a browser (macOS/Windows)
+        if: runner.os != 'Linux'
+        env:
+          EXECWEAVE_E2E_REQUIRED: "1"
+          EXECWEAVE_VISUAL_ARTIFACT_DIR: visual-artifacts
+        run: python -m pytest -m viewer_e2e -v --junitxml=viewer-pytest-results.xml
+
+      - name: Annotate viewer pytest failures
+        if: failure() && hashFiles('viewer-pytest-results.xml') != ''
+        run: python scripts/annotate_pytest_failures.py viewer-pytest-results.xml
+
+      - name: Run formal offline dashboard acceptance
+        run: >-
+          python scripts/dashboard_acceptance.py
+          --mode offline
+          --output-dir "${{ github.workspace }}/artifacts/dashboard-acceptance"
+          --require offline-ollama-fixture
+
+      - name: Run formal owned-process cleanup acceptance
+        run: >-
+          python scripts/owned_cleanup_acceptance.py
+          --output-dir "${{ github.workspace }}/artifacts/dashboard-acceptance/owned-cleanup"
+
+      - name: Run formal native Python OS acceptance (Linux)
+        if: runner.os == 'Linux'
+        run: >-
+          xvfb-run -a python scripts/python_native_acceptance.py
+          --output-dir "${{ github.workspace }}/artifacts/dashboard-acceptance/python-native"
+          --require python
+
+      - name: Run formal native Python OS acceptance (macOS/Windows)
+        if: runner.os != 'Linux'
+        run: >-
+          python scripts/python_native_acceptance.py
+          --output-dir "${{ github.workspace }}/artifacts/dashboard-acceptance/python-native"
+          --require python
+
+      - name: Upload visual release evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: unified-dashboard-visuals-${{ matrix.os }}
+          path: |
+            visual-artifacts
+            artifacts/dashboard-acceptance
+          if-no-files-found: error
+          retention-days: 7

{execweave-0.8.11 → execweave-0.8.13}/.gitignore

@@ -8,3 +8,5 @@ dist/
 build/
 *.egg-info/
 .execweave/
+.execweave-acceptance/
+artifacts/dashboard-acceptance/

execweave-0.8.13/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.5
+Name: execweave
+Version: 0.8.13
+Summary: Turn AI-agent runtime behavior into a local interactive execution graph.
+Project-URL: Homepage, https://github.com/Irish-kw/ExecWeave
+Project-URL: Repository, https://github.com/Irish-kw/ExecWeave
+Project-URL: Documentation, https://github.com/Irish-kw/ExecWeave#documentation
+Project-URL: Issues, https://github.com/Irish-kw/ExecWeave/issues
+Author: ExecWeave contributors
+License: PolyForm Noncommercial License 1.0.0
+        
+        This software is licensed under the PolyForm Noncommercial License 1.0.0.
+        The complete license terms are available at:
+        https://polyformproject.org/licenses/noncommercial/1.0.0
+        
+        Required Notice: Copyright (c) 2026 GWW
+        
+        Commercial use is not permitted under this license. Any commercial use,
+        including use in or for a commercial product or service, requires a separate
+        written commercial license from the licensor.
+        
+        For the avoidance of doubt, this license change applies to versions released
+        under these terms. Earlier versions that were already distributed under the
+        MIT License remain available under the license terms that accompanied those
+        versions.
+License-File: LICENSE
+Keywords: ai-agents,execution-graph,observability,provenance,runtime,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: psutil>=5.9
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pywinpty<4,>=3.0.5; (platform_system == 'Windows') and extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Provides-Extra: e2e
+Requires-Dist: playwright>=1.44; extra == 'e2e'
+Requires-Dist: pywinpty<4,>=3.0.5; (platform_system == 'Windows') and extra == 'e2e'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=6.0; extra == 'release'
+Description-Content-Type: text/markdown
+
+# ExecWeave
+
+<!-- i18n-nav:start -->
+<p align="center">
+  <strong>English</strong> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.ja.md">日本語</a> |
+  <a href="README.ko.md">한국어</a> |
+  <a href="README.fr.md">Français</a> |
+  <a href="README.de.md">Deutsch</a> |
+  <a href="README.ru.md">Русский</a>
+</p>
+<!-- i18n-nav:end -->
+
+<p align="center">
+  <a href="https://pypi.org/project/execweave/"><img src="https://img.shields.io/pypi/v/execweave" alt="PyPI"></a>
+  <a href="https://github.com/Irish-kw/ExecWeave/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Irish-kw/ExecWeave/ci.yml?branch=main" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue" alt="License"></a>
+</p>
+
+**See what AI agents actually do on your machine.**
+
+ExecWeave is a local-first observability project for AI agents and AI-assisted development tools. It combines provider-level semantics with operating-system runtime evidence and presents them as one interactive execution graph.
+
+> **Events are evidence. The graph is a materialized view.**
+
+<p align="center">
+  <img src="docs/assets/codex.gif" alt="ExecWeave live dashboard demo" width="100%">
+</p>
+
+## Why ExecWeave
+
+An agent can say it used a tool, edited a file, or contacted a service. That is useful semantic evidence, but it is not the same as observing what happened on the machine. ExecWeave keeps those layers separate and lets you inspect them together.
+
+- **One dashboard for live and finished runs.** The live page, completed run, and standalone `viewer.html` use the same graph and conversation model.
+- **Provider-aware semantics.** Hooks, rollout transcripts, plugins, and runtime APIs are used when a provider exposes them.
+- **OS-runtime evidence.** Processes, files, and network endpoints can be observed independently of provider semantics.
+- **Evidence-aware attribution.** Direct observations, exact identities, conservative inference, and causal claims are not flattened into one label.
+- **Local-first storage.** Run artifacts stay on the machine unless you choose to copy or share them.
+- **Works beyond one agent.** You can wrap ordinary local commands even when no specialized provider adapter exists.
+
+## Install
+
+Install from PyPI:
+
+```bash
+python -m pip install -U execweave
+```
+
+For development:
+
+```bash
+git clone https://github.com/Irish-kw/ExecWeave.git
+cd ExecWeave
+python -m pip install -e ".[dev]"
+```
+
+## Quick start
+
+Wrap any local command with `execweave live`:
+
+```bash
+execweave live --open -- claude
+execweave live --open -- codex
+execweave live --open -- antigravity
+execweave live --open -- cursor
+execweave live --open -- opencode
+execweave live --open -- python my_agent.py
+```
+
+Use `record` when you mainly want finalized artifacts:
+
+```bash
+execweave record --open -- python my_agent.py
+```
+
+Use `top` when you want a detached overview while keeping the launched program interactive in the current terminal:
+
+```bash
+execweave top -- codex
+```
+
+### Provider integration approval
+
+Some agents and IDEs ask for permission before enabling a local hook or plugin. Approve the ExecWeave integration if you want provider-level prompt, response, tool, model, and conversation evidence. If you do not approve it, OS-runtime observation can still work, but semantic coverage may be reduced.
+
+Google Antigravity currently uses the `agy` CLI command. ExecWeave also accepts `antigravity` as a friendly alias.
+
+On Windows, bare `cursor` follows the Cursor installation referenced by the user's PATH. Explicit launcher paths are respected.
+
+## Ollama
+
+ExecWeave supports two common local Ollama workflows.
+
+### Managed server capture
+
+Start Ollama through ExecWeave:
+
+```bash
+execweave live --open -- ollama serve
+```
+
+Then use Ollama normally from another terminal:
+
+```bash
+ollama run deepseek-r1:1.5b
+```
+
+SDK calls, OpenAI-compatible local requests, and `curl` requests that reach the managed local endpoint can be associated with the same ExecWeave run. The second terminal does not need another ExecWeave wrapper.
+
+Managed relay mode is intentionally limited to local loopback endpoints. ExecWeave does not rewrite wildcard or externally exposed Ollama listeners.
+
+### Direct client capture
+
+If an Ollama server is already running, you can wrap the client directly:
+
+```bash
+execweave live --open -- ollama run deepseek-r1:1.5b
+```
+
+This mode does not start an Ollama server. A reachable upstream server is still required.
+
+## Dashboard
+
+The dashboard is designed to keep large, multi-agent runs inspectable without changing the underlying evidence.
+
+- **Execution graph:** agents, processes, files, network endpoints, tools, model/runtime entities, and supported relations.
+- **Conversation rounds:** recent and historical rounds remain associated with the correct agent instead of being overwritten by later messages.
+- **Node details:** inspect process identity, file history, network endpoints, tools, and provider conversation content.
+- **Stable live updates:** the dashboard updates in place instead of replacing the whole document when a run changes state.
+- **Large-run folding:** high-cardinality node types can collapse older members while keeping them inspectable.
+- **Selection-focused layout:** selecting an agent or runtime object de-emphasizes unrelated graph traffic.
+
+You can tune large-run rendering with:
+
+```text
+--fold-budget N
+--viewer-max-nodes N
+--viewer-max-edges N
+--viewer-max-dom-elements N
+```
+
+## Supported integrations
+
+| Integration | OS-runtime observation | Specialized evidence |
+| --- | --- | --- |
+| Claude Code | Yes when launched under ExecWeave | native hooks and provider-supplied conversation/tool content |
+| OpenAI Codex | Yes | lifecycle hooks, validated rollout transcripts, agent/subagent routing where exposed |
+| Google Antigravity | Yes | passive hooks and conversation/subagent routing where exposed |
+| Cursor | Yes | native hooks and task/subagent routing where exposed |
+| OpenCode | Yes | project plugin, session/task routing, supplied plugin content |
+| Ollama | Yes | managed local relay and model-runtime evidence |
+| llama.cpp | Yes | model-runtime event/exchange/probe integration |
+| vLLM | Yes | model-runtime event/exchange/probe integration |
+| LM Studio | When the local process is observed | model-runtime catalog/runtime evidence |
+| LiteLLM Proxy | When the local proxy is observed | gateway metadata and event integration |
+| OpenRouter | Local client only; the remote service process is not observable | caller-supplied gateway event/exchange evidence |
+
+Provider identifiers such as a tool-call ID, session ID, rollout thread ID, or subagent route are logical identities. They are not automatically OS process IDs. ExecWeave links layers only when the available evidence supports the link.
+
+## Evidence model
+
+ExecWeave separates four broad layers:
+
+```text
+Agent / IDE semantics and supplied content
+                ↓
+Inference gateway / routing evidence
+                ↓
+Model runtime / inference-server evidence
+                ↓
+OS runtime evidence: process / file / network
+```
+
+A relationship is marked causal only when the underlying telemetry supports a causal claim. Conservative bridges remain explicit derived evidence, for example:
+
+```text
+inferred: true
+causal: false
+```
+
+An exact shared request identity can prove identity without proving causality:
+
+```text
+identity_exact: true
+inferred: false
+causal: false
+```
+
+If attribution is ambiguous, ExecWeave should leave the edge absent rather than invent a stronger relationship.
+
+### Full-fidelity supplied content
+
+Supported integrations can preserve complete values explicitly supplied by provider hooks, plugins, or APIs in a local SHA-256 content-addressed store:
+
+```text
+<run-root>/content/sha256/<sha256>.<json|txt|bin>
+```
+
+Depending on the integration, this can include prompts, messages, request/response objects, tool inputs/results, assistant responses, exposed reasoning text, shell output, and supplied file content.
+
+`complete_from_source: true` means ExecWeave stored the complete value delivered by that integration point. It does **not** mean ExecWeave observed hidden model state or provider-side data that was never exposed.
+
+## Common commands
+
+### Agent and IDE recorders
+
+```bash
+execweave-claude-record --open -- claude
+execweave-codex-record --open -- codex
+execweave-antigravity-record --open -- antigravity
+execweave-cursor-record --open -- cursor
+execweave-opencode-plugin --install
+execweave-opencode-record --open -- opencode
+```
+
+### Gateways and model runtimes
+
+```bash
+execweave-inference-gateway event --gateway openrouter --sidecar gateway.jsonl
+execweave-inference-gateway exchange --gateway openrouter --sidecar gateway.jsonl
+execweave-model-runtime event --runtime ollama --sidecar model-runtime.jsonl
+execweave-model-runtime exchange --runtime ollama --sidecar model-runtime.jsonl
+execweave-model-runtime probe --runtime ollama --sidecar model-runtime.jsonl
+```
+
+`event` records one-sided event evidence. `exchange` records a caller-supplied request/response pair; it does not claim transparent wire interception.
+
+### Runtime, graph, security, and integrity
+
+```bash
+execweave doctor
+execweave run --backend portable -- your-command
+execweave run --backend strace -- your-command
+execweave graph-summary run.graph.json
+execweave graph-filter run.graph.json --causal-only --output causal.graph.json
+execweave graph-focus run.graph.json NODE_ID --hops 2 --output focused.graph.json
+execweave path run.graph.json SOURCE TARGET --causal-only
+execweave analyze run.graph.json --output analysis.json
+execweave-rule-pack graph.json --rule-pack local-policy.json --output report.json
+execweave-integrity seal .execweave/runs/<run-id>
+execweave-integrity verify .execweave/runs/<run-id>
+```
+
+## Run artifacts
+
+A provider-integrated run can contain:
+
+```text
+.execweave/runs/<run-id>/
+├── events.jsonl
+├── graph.json
+├── viewer.html
+├── semantic.jsonl
+├── content/sha256/...
+├── conversations.md
+├── conversations.json
+├── events.semantic.jsonl
+├── graph.semantic.json
+├── viewer.semantic.html
+├── events.correlated.jsonl
+├── graph.correlated.json
+├── viewer.correlated.html
+└── integrity.json
+```
+
+Raw observations remain separate from derived semantic and correlation outputs.
+
+## Limits and privacy
+
+- The portable collector runs on Linux, macOS, and Windows. Portable filesystem observation is session-correlated rather than always process-causal, and polling can miss sufficiently short-lived activity.
+- **Process lifetime identity:** portable process tracking distinguishes PID reuse with the process creation time. A reused PID is recorded as a new process lifetime instead of being collapsed into the earlier process.
+- **Explicit degraded-state reporting:** terminal network collection health is reported as `available`, `degraded`, `unavailable`, `not_sampled`, or `not_requested`. A finished live conversation is considered synchronized only after the final conversation fetch succeeds; stopping polling alone is not treated as successful synchronization.
+- **Failure ownership cleanup:** if the portable collector fails unexpectedly after launching a managed workload, it terminates the workload it owns before recording terminal session state. A filesystem observer that only partially starts is also torn down before the startup error propagates.
+- Linux also provides a `strace` reference backend with stronger syscall-attributed evidence for supported executions.
+- Provider semantics depend on what each integration actually exposes. Missing prompts, hidden reasoning, remote provider internals, and unexposed routing cannot be reconstructed reliably.
+- Full-fidelity provider content may contain credentials, secrets, source code, prompts, tool values, model responses, shell output, and file contents.
+- Conversation isolation is an attribution rule, not a redaction boundary. Explicitly routed content may legitimately appear at more than one participant.
+- A local integrity manifest detects changes relative to the manifest; it is not an adversary-resistant trusted logging system if both evidence and manifest remain inside the same writable trust boundary.
+- Review the complete run directory before sharing it.
+
+## Development
+
+Run the test suite:
+
+```bash
+python -m pytest
+```
+
+Run linting:
+
+```bash
+python -m ruff check .
+```
+
+Issues and pull requests are welcome. Keep new integrations evidence-aware: document what is directly observed, what is supplied by the provider, and what is derived.
+
+## License
+
+ExecWeave is distributed under the **PolyForm Noncommercial License 1.0.0**. See [LICENSE](LICENSE) for the full terms.