stata-code 0.6.3__tar.gz → 0.6.5__tar.gz

{stata_code-0.6.3 → stata_code-0.6.5}/CHANGELOG.md

@@ -6,6 +6,61 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ## Unreleased
 
+## 0.6.5 — 2026-05-22
+
+### Fixed
+
+- **OpenAI tool-schema compatibility.** `notebook_locate` and
+  `notebook_insert_cell` no longer advertise top-level `oneOf` constraints in
+  their MCP input schemas. OpenAI rejects those schemas during tool
+  registration, while the server-side runtime guards still enforce the
+  "exactly one query/anchor" rules.
+
+## 0.6.4 — 2026-05-21
+
+### Added
+
+- **Claude Code plugin marketplace manifest.** `.claude-plugin/marketplace.json`
+  + `.claude-plugin/plugin.json` expose the repo as a single-plugin
+  marketplace, so users can install everything (MCP server config + agent
+  skill) with `claude plugin marketplace add brycewang-stanford/stata-code`
+  followed by `claude plugin install stata-code`.
+- **`stata-code` agent skill.** `skills/stata-code/SKILL.md` teaches Claude
+  the v1.0 RunResult schema, the 15 MCP tools, the token-economy defaults,
+  the 32-kind error taxonomy, and the diagnose-only vs. fix-and-rerun
+  workflows. The plugin manifest auto-installs it alongside the MCP
+  server.
+- **VS Code install-hint probe.** On activation the extension now resolves
+  the configured `stata-code-mcp` candidate list against `PATH` and any
+  workspace `.venv` / `venv`; if nothing matches, a one-time notification
+  offers to copy the `pip install "stata-code[mcp]"` command or open the
+  install docs. "Don't show again" pins the dismissal to the installed
+  extension version. Backed by a new pure module `serverProbe.ts` with
+  unit tests.
+- **README multi-client section.** Cursor, Claude Desktop, Cline,
+  Continue, Windsurf, and Antigravity now have their config-file paths
+  spelled out next to the shared `stata-code-mcp` JSON snippet, plus
+  guidance for project-venv absolute paths and `uvx` setups.
+- **README cell + section reference.** Documents that the VS Code
+  extension recognizes both `* %%` Jupyter-style cell markers and
+  `**#` … `**######` six-level section headings in `.do` files, and how
+  each interacts with the code-lens and Outline view.
+- **Open VSX publish step.** `vscode-release.yml` now publishes the VSIX
+  to Open VSX on every `vscode-v*` tag. The step is gated on
+  `OVSX_PAT` being set at runtime and runs with `continue-on-error: true`,
+  so a missing or expired token never blocks the primary VS Code
+  Marketplace publish.
+
+### Fixed
+
+- **Subprocess worker JSON protocol hardening.** Worker processes now keep
+  their private JSON protocol fds separate from real stdin/stdout and
+  redirect the real fd 0/1 pair to `os.devnull` before importing the
+  runner. The parent reader also ignores blank protocol noise while still
+  failing on non-empty non-JSON output. This prevents a pystata/Stata
+  initialization newline from surfacing as
+  `adapter_crash: worker emitted non-JSON: '\n'`.
+
 ## 0.6.3 — 2026-05-10
 
 ### Added

{stata_code-0.6.3 → stata_code-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.6.3
+Version: 0.6.5
 Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
 Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
 Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
@@ -84,7 +84,7 @@ Description-Content-Type: text/markdown
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. Current test suite: 329 passing tests across schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules. License: **MIT**.
+**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
 Two workflows v0.6 explicitly supports for end users:
 
@@ -204,14 +204,34 @@ If you want the repair loop, say so explicitly. Otherwise, treat failed runs as
 If you prefer not to `pip install stata-code` globally, run it ephemerally through [`uv`](https://github.com/astral-sh/uv):
 
 ```bash
-claude mcp add stata-code --scope user -- uvx --from stata-code stata-code-mcp
+claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp
 ```
 
 `uvx` will resolve and cache `stata-code` on first launch. Note: `pystata` is **not** on PyPI, so it still has to be locatable on the host. The runner adds the standard Stata install path (e.g. `/Applications/Stata/utilities/pystata` on macOS) to `sys.path` automatically; if your Stata lives elsewhere, set `PYTHONPATH` in the env block.
 
-#### Manual JSON config (Cursor / Claude Desktop / fallback)
+#### Claude Code via plugin marketplace
 
-For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/mcp.json`, Cursor settings, Claude Desktop `claude_desktop_config.json`, etc.):
+This repository also ships a Claude Code plugin manifest (`.claude-plugin/`). Once you've added the marketplace to your Claude Code config, two commands wire up both the MCP server and the agent skill that teaches Claude the v1.0 result schema:
+
+```bash
+claude plugin marketplace add brycewang-stanford/stata-code
+claude plugin install stata-code
+```
+
+The plugin registers the `stata-code` MCP server and installs the [`stata-code` skill](skills/stata-code/SKILL.md) so Claude branches on `error.kind`, calls `get_log(ref)` lazily, and uses the notebook-edit tools without you re-explaining them every session.
+
+#### Other MCP clients (Cursor / Claude Desktop / Cline / Continue / Windsurf / Antigravity)
+
+Most non-Claude-Code MCP clients accept the same JSON snippet. Drop it into the client's MCP config file:
+
+| Client | Config file |
+| --- | --- |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (user) or `<workspace>/.cursor/mcp.json` (project) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline (VS Code) | settings: `cline.mcpServers` |
+| Continue | `~/.continue/config.json` under `experimental.modelContextProtocolServers` |
+| Antigravity / generic | `~/.claude/mcp.json` or whatever the client documents |
 
 ```json
 {
@@ -223,12 +243,39 @@ For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/m
 }
 ```
 
-Or run it as a module if the binary is not on `PATH`:
+Or, when the binary is not on `PATH`, run it as a module:
 
 ```bash
 python -m stata_code.mcp
 ```
 
+When `stata-code-mcp` lives inside a project virtualenv (recommended for reproducibility), point the client at the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "stata-code": {
+      "command": "/abs/path/to/.venv/bin/stata-code-mcp"
+    }
+  }
+}
+```
+
+For `uvx`-only setups, set `"command": "uvx"` and `"args": ["--from", "stata-code", "stata-code-mcp"]`.
+
+#### MCP troubleshooting
+
+If `stata_run` reports `adapter_crash` with `worker emitted non-JSON: '\n'`,
+upgrade to `stata-code>=0.6.4`, then restart the MCP client so it launches a
+fresh server process. Also check that the client is resolving the expected
+`stata-code-mcp` binary; project virtualenv installs should use the absolute
+`.venv/bin/stata-code-mcp` path instead of relying on a global `PATH` entry.
+
+If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
+'mcp__stata-code__notebook_insert_cell'` and mentions a top-level `oneOf`,
+upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
+processes keep advertising the stale schema until they are restarted.
+
 The MCP server registers 15 tools:
 
 | Tool | Purpose |
@@ -239,7 +286,7 @@ The MCP server registers 15 tools:
 | `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
 | `list_sessions` | Enumerate live sessions |
-| `cancel_session` | Cooperatively cancel the next `stata_run` for a session |
+| `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
 | `reset_session` | Drop a session's data |
 | `notebook_outline` | Compact per-cell index of a `.ipynb` (cell_id, type, preview) |
 | `notebook_get_cell` | One cell's full source plus a token-economic outputs summary |
@@ -304,7 +351,20 @@ The companion extension is on the Marketplace as [`brycewang-stanford.stata-code
 code --install-extension brycewang-stanford.stata-code-vscode
 ```
 
-Or open the **Extensions** sidebar in VS Code and search `stata-code`.
+Or open the **Extensions** sidebar in VS Code and search `stata-code`. The extension is also available from [Open VSX](https://open-vsx.org/) so Cursor, Windsurf, and other VS Code-compatible editors can install it without going through the Microsoft Marketplace.
+
+On first activation the extension probes for `stata-code-mcp` on `PATH` (and in any workspace `.venv` / `venv`). If nothing resolves, it shows a one-time install hint with the exact `pip install "stata-code[mcp]"` command — choose **Don't show again** to silence it for the installed extension version.
+
+#### Cell and section conventions
+
+The extension recognizes two complementary structural markers inside `.do` files. Either can be mixed in the same file; they do not conflict.
+
+| Marker | Purpose | Example |
+| --- | --- | --- |
+| `* %% [title]` | Cell boundary. Each marker gets a **▶ Run Cell** code-lens; "Run Cell" submits the lines between this marker and the next one. Compatible with the Jupyter-style cell convention used by `kylebutts/vscode-stata`. | `* %% 02 model fit` |
+| `**# title` … `**###### title` | Section heading, 1–6 levels deep. Each heading gets a **▶ Run Section** code-lens and contributes to the Outline view. "Run Section" submits the heading through the next equal- or higher-level heading, matching the hierarchical execution model from `ZihaoVistonWang.stata-all-in-one`. | `**## DiD specification` |
+
+`program define … end` blocks are also surfaced in the Outline, nested under whichever section contains them.
 
 The extension still requires the MCP extra on your system Python (`pip install "stata-code[mcp]"`), so that `stata-code-mcp` resolves on `PATH` and can import the MCP SDK. Stata 17+ and a valid Stata license are required as for any other frontend.
 
@@ -397,7 +457,7 @@ stata_code/
 - MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
 - Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
-- Cooperative cancellation: `cancel(session_id)` / MCP `cancel_session`
+- Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
 - Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
@@ -407,8 +467,8 @@ stata_code/
 ### Next Up
 
 - Console fallback for Stata 11–16, re-implemented against the v1.0 schema
-- Hard timeout / mid-Stata interrupt; design and tradeoffs in [`docs/design/hard_timeout.md`](docs/design/hard_timeout.md)
-- Extra VS Code polish (esbuild bundle, lighter VSIX, command palette UX)
+- Decide whether to move the Jupyter kernel from the direct in-process runner to the subprocess pool, or keep documenting the current interactivity-first tradeoff
+- Extra VS Code polish: extension-host end-to-end tests, first-run diagnostics, and command palette UX
 - **v1.0** — Stable schema, broader Stata edition coverage
 
 See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
@@ -419,9 +479,9 @@ See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
 
 ```bash
 pip install -e ".[dev,mcp,kernel]"
-pytest                              # full suite (310 tests)
+pytest                              # full suite, including Stata tests when Stata is available
 pytest -m "not stata_required"      # CI subset; no Stata needed
-pytest -m "stata_required" -v       # Stata-only integration tests
+pytest -m "stata_required" -v       # real-Stata integration tests only
 ```
 
 The `stata_required` marker tags the real-Stata integration tests. CI uses `pytest -m "not stata_required"` so it does not collect them. Locally without Stata, those tests skip cleanly with the `"pystata / Stata 17+ not available"` message.

{stata_code-0.6.3 → stata_code-0.6.5}/PUBLISHING.md

@@ -1,8 +1,9 @@
-# Publishing `stata-code` to PyPI
+# Publishing `stata-code` to TestPyPI and PyPI
 
-This project publishes to PyPI via **GitHub Actions Trusted Publishing** (OIDC).
-There are **no API tokens** stored in GitHub repository secrets — PyPI verifies
-the OIDC identity of the workflow run instead.
+This project publishes to TestPyPI and PyPI via **GitHub Actions Trusted
+Publishing** (OIDC). There are **no API tokens** stored in GitHub repository
+secrets — each package index verifies the OIDC identity of the workflow run
+instead.
 
 The release pipeline is in [`.github/workflows/release.yml`](.github/workflows/release.yml).
 
@@ -28,25 +29,34 @@ Trusted Publishing has two modes:
 
 Either path lands you in the same place after the first run.
 
-### 2. Configure the Trusted Publisher on PyPI
+### 2. Configure the Trusted Publishers
 
-On the PyPI publishing page, add a GitHub publisher with these values:
+PyPI and TestPyPI are separate package indexes, so configure both publisher
+records independently:
 
-| Field | Value |
-| --- | --- |
-| Owner | `brycewang-stanford` |
-| Repository name | `stata-code` |
-| Workflow filename | `release.yml` |
-| Environment name | `pypi` |
+| Site | Manage URL | Environment |
+| --- | --- | --- |
+| PyPI | <https://pypi.org/manage/project/stata-code/settings/publishing/> | `pypi` |
+| TestPyPI | <https://test.pypi.org/manage/project/stata-code/settings/publishing/> | `testpypi` |
+
+Use the same GitHub publisher values on both sites:
+
+- Owner: `brycewang-stanford`
+- Repository name: `stata-code`
+- Workflow filename: `release.yml`
+- Environment name: `pypi` or `testpypi`, matching the site above
 
 The environment name is **required** and must match the `environment.name`
-declared in `release.yml` (`pypi`). PyPI uses it as an extra constraint:
+declared in `release.yml`. PyPI / TestPyPI use it as an extra constraint:
 even a malicious workflow change in the repo cannot publish unless it runs
-under that exact environment.
+under the exact environment configured for that index.
+
+### 3. Create the GitHub Environments
 
-### 3. Create the GitHub Environment
+In the GitHub repo: **Settings → Environments → New environment**. Create both:
 
-In the GitHub repo: **Settings → Environments → New environment → name `pypi`**.
+- `testpypi`
+- `pypi`
 
 Recommended hardening (all in the environment settings page):
 
@@ -66,25 +76,38 @@ The environment doesn't need any secrets — Trusted Publishing handles auth.
 
 Once the one-time setup above is done, every release is just:
 
-1. **Bump the version** in `pyproject.toml` (`[project] version`).
-2. **Update `CHANGELOG.md`**: move the `[Unreleased]` entries under a new
+1. **Bump the version everywhere**:
+   - `pyproject.toml` → `[project] version`
+   - `stata_code/__init__.py` → `__version__`
+   - `stata_code/mcp/server.py` → `__version__`
+   - `vscode/package.json` → `version`
+   - `vscode/package-lock.json` → root package `version`
+2. **Run the version guard** before tagging:
+   ```bash
+   python scripts/check_versions.py
+   ```
+3. **Update `CHANGELOG.md`**: move the `[Unreleased]` entries under a new
    `## [X.Y.Z] - YYYY-MM-DD` heading, leaving an empty `[Unreleased]` shell
    on top.
-3. **Commit** the bump:
+4. **Commit** the bump:
    ```bash
-   git add pyproject.toml CHANGELOG.md
+   git add pyproject.toml stata_code/__init__.py stata_code/mcp/server.py vscode/package.json vscode/package-lock.json CHANGELOG.md
    git commit -m "release: vX.Y.Z"
    ```
-4. **Tag and push**:
+5. **Tag and push**:
    ```bash
    git tag vX.Y.Z
    git push origin main
    git push origin vX.Y.Z
    ```
-5. Watch the **`release` workflow** under the Actions tab. It will:
+6. Watch the **`release` workflow** under the Actions tab. It will:
    - build the sdist + wheel
    - run `twine check` on the artifacts
+   - publish to TestPyPI under the `testpypi` environment (no token needed)
    - publish to PyPI under the `pypi` environment (no token needed)
+   - poll PyPI's per-version JSON endpoint so a failed trusted-publisher
+     publish marks the workflow run failed even though the publish job itself
+     is `continue-on-error`
    - create a GitHub Release for the tag with the wheel + sdist attached and
      auto-generated release notes
 

{stata_code-0.6.3 → stata_code-0.6.5}/README.md

@@ -45,7 +45,7 @@
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. Current test suite: 329 passing tests across schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules. License: **MIT**.
+**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
 Two workflows v0.6 explicitly supports for end users:
 
@@ -165,14 +165,34 @@ If you want the repair loop, say so explicitly. Otherwise, treat failed runs as
 If you prefer not to `pip install stata-code` globally, run it ephemerally through [`uv`](https://github.com/astral-sh/uv):
 
 ```bash
-claude mcp add stata-code --scope user -- uvx --from stata-code stata-code-mcp
+claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp
 ```
 
 `uvx` will resolve and cache `stata-code` on first launch. Note: `pystata` is **not** on PyPI, so it still has to be locatable on the host. The runner adds the standard Stata install path (e.g. `/Applications/Stata/utilities/pystata` on macOS) to `sys.path` automatically; if your Stata lives elsewhere, set `PYTHONPATH` in the env block.
 
-#### Manual JSON config (Cursor / Claude Desktop / fallback)
+#### Claude Code via plugin marketplace
 
-For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/mcp.json`, Cursor settings, Claude Desktop `claude_desktop_config.json`, etc.):
+This repository also ships a Claude Code plugin manifest (`.claude-plugin/`). Once you've added the marketplace to your Claude Code config, two commands wire up both the MCP server and the agent skill that teaches Claude the v1.0 result schema:
+
+```bash
+claude plugin marketplace add brycewang-stanford/stata-code
+claude plugin install stata-code
+```
+
+The plugin registers the `stata-code` MCP server and installs the [`stata-code` skill](skills/stata-code/SKILL.md) so Claude branches on `error.kind`, calls `get_log(ref)` lazily, and uses the notebook-edit tools without you re-explaining them every session.
+
+#### Other MCP clients (Cursor / Claude Desktop / Cline / Continue / Windsurf / Antigravity)
+
+Most non-Claude-Code MCP clients accept the same JSON snippet. Drop it into the client's MCP config file:
+
+| Client | Config file |
+| --- | --- |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (user) or `<workspace>/.cursor/mcp.json` (project) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline (VS Code) | settings: `cline.mcpServers` |
+| Continue | `~/.continue/config.json` under `experimental.modelContextProtocolServers` |
+| Antigravity / generic | `~/.claude/mcp.json` or whatever the client documents |
 
 ```json
 {
@@ -184,12 +204,39 @@ For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/m
 }
 ```
 
-Or run it as a module if the binary is not on `PATH`:
+Or, when the binary is not on `PATH`, run it as a module:
 
 ```bash
 python -m stata_code.mcp
 ```
 
+When `stata-code-mcp` lives inside a project virtualenv (recommended for reproducibility), point the client at the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "stata-code": {
+      "command": "/abs/path/to/.venv/bin/stata-code-mcp"
+    }
+  }
+}
+```
+
+For `uvx`-only setups, set `"command": "uvx"` and `"args": ["--from", "stata-code", "stata-code-mcp"]`.
+
+#### MCP troubleshooting
+
+If `stata_run` reports `adapter_crash` with `worker emitted non-JSON: '\n'`,
+upgrade to `stata-code>=0.6.4`, then restart the MCP client so it launches a
+fresh server process. Also check that the client is resolving the expected
+`stata-code-mcp` binary; project virtualenv installs should use the absolute
+`.venv/bin/stata-code-mcp` path instead of relying on a global `PATH` entry.
+
+If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
+'mcp__stata-code__notebook_insert_cell'` and mentions a top-level `oneOf`,
+upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
+processes keep advertising the stale schema until they are restarted.
+
 The MCP server registers 15 tools:
 
 | Tool | Purpose |
@@ -200,7 +247,7 @@ The MCP server registers 15 tools:
 | `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
 | `list_sessions` | Enumerate live sessions |
-| `cancel_session` | Cooperatively cancel the next `stata_run` for a session |
+| `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
 | `reset_session` | Drop a session's data |
 | `notebook_outline` | Compact per-cell index of a `.ipynb` (cell_id, type, preview) |
 | `notebook_get_cell` | One cell's full source plus a token-economic outputs summary |
@@ -265,7 +312,20 @@ The companion extension is on the Marketplace as [`brycewang-stanford.stata-code
 code --install-extension brycewang-stanford.stata-code-vscode
 ```
 
-Or open the **Extensions** sidebar in VS Code and search `stata-code`.
+Or open the **Extensions** sidebar in VS Code and search `stata-code`. The extension is also available from [Open VSX](https://open-vsx.org/) so Cursor, Windsurf, and other VS Code-compatible editors can install it without going through the Microsoft Marketplace.
+
+On first activation the extension probes for `stata-code-mcp` on `PATH` (and in any workspace `.venv` / `venv`). If nothing resolves, it shows a one-time install hint with the exact `pip install "stata-code[mcp]"` command — choose **Don't show again** to silence it for the installed extension version.
+
+#### Cell and section conventions
+
+The extension recognizes two complementary structural markers inside `.do` files. Either can be mixed in the same file; they do not conflict.
+
+| Marker | Purpose | Example |
+| --- | --- | --- |
+| `* %% [title]` | Cell boundary. Each marker gets a **▶ Run Cell** code-lens; "Run Cell" submits the lines between this marker and the next one. Compatible with the Jupyter-style cell convention used by `kylebutts/vscode-stata`. | `* %% 02 model fit` |
+| `**# title` … `**###### title` | Section heading, 1–6 levels deep. Each heading gets a **▶ Run Section** code-lens and contributes to the Outline view. "Run Section" submits the heading through the next equal- or higher-level heading, matching the hierarchical execution model from `ZihaoVistonWang.stata-all-in-one`. | `**## DiD specification` |
+
+`program define … end` blocks are also surfaced in the Outline, nested under whichever section contains them.
 
 The extension still requires the MCP extra on your system Python (`pip install "stata-code[mcp]"`), so that `stata-code-mcp` resolves on `PATH` and can import the MCP SDK. Stata 17+ and a valid Stata license are required as for any other frontend.
 
@@ -358,7 +418,7 @@ stata_code/
 - MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
 - Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
-- Cooperative cancellation: `cancel(session_id)` / MCP `cancel_session`
+- Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
 - Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
@@ -368,8 +428,8 @@ stata_code/
 ### Next Up
 
 - Console fallback for Stata 11–16, re-implemented against the v1.0 schema
-- Hard timeout / mid-Stata interrupt; design and tradeoffs in [`docs/design/hard_timeout.md`](docs/design/hard_timeout.md)
-- Extra VS Code polish (esbuild bundle, lighter VSIX, command palette UX)
+- Decide whether to move the Jupyter kernel from the direct in-process runner to the subprocess pool, or keep documenting the current interactivity-first tradeoff
+- Extra VS Code polish: extension-host end-to-end tests, first-run diagnostics, and command palette UX
 - **v1.0** — Stable schema, broader Stata edition coverage
 
 See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
@@ -380,9 +440,9 @@ See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
 
 ```bash
 pip install -e ".[dev,mcp,kernel]"
-pytest                              # full suite (310 tests)
+pytest                              # full suite, including Stata tests when Stata is available
 pytest -m "not stata_required"      # CI subset; no Stata needed
-pytest -m "stata_required" -v       # Stata-only integration tests
+pytest -m "stata_required" -v       # real-Stata integration tests only
 ```
 
 The `stata_required` marker tags the real-Stata integration tests. CI uses `pytest -m "not stata_required"` so it does not collect them. Locally without Stata, those tests skip cleanly with the `"pystata / Stata 17+ not available"` message.

{stata_code-0.6.3 → stata_code-0.6.5}/SCHEMA.md

@@ -430,7 +430,7 @@ Suggestions are best-effort; agents should treat them as hints, not directives.
 | `stata_limit` | 901, 902, 903 | Edition / matsize / similar Stata-imposed caps. Distinct from OS OOM. Suggestion: `set maxvar` or upgrade edition. |
 | `out_of_memory` | 480, 909 | OS-level memory exhaustion. |
 | `interrupt` | 1 | User Break / Ctrl-C from a frontend. |
-| `cancelled` | (synthetic `rc: -3`) | Cooperative cancellation: a prior `cancel(session_id)` short-circuited this run before Stata received the code. |
+| `cancelled` | (synthetic `rc: -3`) | Cancellation was requested. Subprocess-backed producers may terminate an in-flight worker; the direct in-process runner only short-circuits before Stata receives code. |
 | `timeout` | (synthetic `rc: -2`) | Adapter-imposed time limit exceeded. |
 | `adapter_crash` | (synthetic `rc: -1`) | Producer-side failure (pystata exception, IPC death). |
 | `unknown` | any unmapped rc | Catch-all. Agents fall back to `message`. We aim to shrink this over time. |

{stata_code-0.6.3 → stata_code-0.6.5}/docs/design/hard_timeout.md

@@ -1,14 +1,16 @@
 # Design note: hard timeout / mid-Stata interrupt
 
-> Status: **deferred** — not implemented in v0.2/early-v0.3. This document
-> exists so the next person picking it up has the constraints written
-> down. After this lands, `cooperative cancellation` (shipping in this
-> push) covers the "abort the next call" case; the gap is killing a
-> Stata command that is already executing.
+> Status: **partially shipped**. The public Python API and MCP server now use
+> the subprocess-worker architecture described below (`stata_code.core._pool`),
+> so `timeout_ms` and in-flight `cancel_session` terminate the worker and return
+> structured `timeout` / `cancelled` results. The remaining gap is the direct
+> in-process runner (`stata_code.core.runner.execute`) and the Jupyter kernel,
+> which still use `pystata` in-process for interactivity. This note is retained
+> as the rationale for that boundary.
 
 ## The constraint
 
-`stata_code` runs Stata via **pystata, in-process**. The runner imports
+The direct runner runs Stata via **pystata, in-process**. It imports
 `pystata.config`, calls `pystata.config.init(edition)`, then submits
 code through `stata.run(code)`. That call is a synchronous, blocking C
 call into Stata's runtime. From Python's perspective, the interpreter
@@ -26,7 +28,7 @@ There is **no public pystata API** to:
   is process-wide; a second `init()` is rejected. Frames give us
   data isolation, not control isolation.
 
-So `timeout_ms` cannot be enforced in the current architecture.
+So `timeout_ms` cannot be enforced in the direct in-process runner.
 `cancel(session_id)` (cooperative) catches the case where the agent
 hasn't yet submitted the next command, but if the agent already issued
 `bootstrap, reps(10000): regress …` and is mid-flight, nothing on the
@@ -43,7 +45,7 @@ and a synthetic `rc: -2` for exactly this case.
 
 ## Options considered
 
-### Option A — Subprocess pystata worker (recommended)
+### Option A — Subprocess pystata worker (shipped for public API / MCP)
 
 Move pystata out of the main Python process. One persistent worker
 subprocess per session, with a small JSON-over-stdio protocol:
@@ -140,22 +142,13 @@ When Option A is approved, the rough work breakdown is:
 
 Total: ~8–10 days of focused work.
 
-## Why not now
+## Why not in the direct runner / kernel yet
 
-This v0.3 push deliberately scoped to changes that do not require
-restructuring `_runtime.py`. Shipping Option A as a side-effect of a
-multi-feature push would leave it under-tested and ill-thought-through.
-It deserves its own milestone where (a) the design above is reviewed
-and confirmed, (b) the work is tracked across at least one full
-development week, and (c) any breaking change to the runtime model
-is announced ahead of time so downstream callers can plan.
-
-In the meantime the ground we did cover is real:
-
-- Cooperative cancellation (`cancel(session_id)`) — in this push.
-- Token economy preserved end-to-end (refs, not bytes) — in this push.
-- VSCode webview that exercises the same MCP surface a hard-timeout
-  agent would — in this push.
-
-The hardest piece is still ahead. This document exists so the next
-person picking it up doesn't have to rediscover the constraints.
+The subprocess pool is now the default for the package-level API and MCP
+server. The lower-level `core.runner.execute()` remains available as an
+explicit in-process escape hatch, and the Jupyter kernel still calls it so
+notebook cells can use inline logs and graphs without paying the worker
+round-trip or changing notebook semantics. Moving the kernel onto the pool is
+possible, but should be treated as a separate UX decision: hard interruption
+would improve resilience, while worker death would discard in-memory Stata
+state after timeouts or cancels.

{stata_code-0.6.3 → stata_code-0.6.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stata-code"
-version = "0.6.3"
+version = "0.6.5"
 description = "Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)"
 readme = "README.md"
 license = "MIT"

{stata_code-0.6.3 → stata_code-0.6.5}/stata_code/__init__.py

@@ -174,7 +174,7 @@ def is_available() -> bool:
     return True
 
 
-__version__ = "0.6.3"
+__version__ = "0.6.5"
 
 __all__ = [
     # Primary entry points