mcp-yieldshell 0.6.0__tar.gz → 1.1.0__tar.gz

{mcp_yieldshell-0.6.0 → mcp_yieldshell-1.1.0}/PKG-INFO

@@ -1,31 +1,37 @@
 Metadata-Version: 2.4
 Name: mcp-yieldshell
-Version: 0.6.0
-Summary: A drop-in shell MCP that auto-yields long-running commands into managed background processes.
+Version: 1.1.0
+Summary: A drop-in shell MCP that auto-yields long-running commands into managed background executions.
 Requires-Python: >=3.11
 Requires-Dist: mcp<2,>=1.9.0
 Description-Content-Type: text/markdown
 
 # YieldShell MCP
 
-A drop-in shell MCP server that auto-yields long-running commands into managed background processes.
+A drop-in shell MCP server that auto-yields long-running commands into managed
+background executions.
 
 ## Why Auto-Yielding?
 
 Most shell tools present a frustrating choice: either block the LLM agent until the command finishes, or force the agent to decide upfront that a command should run in the background.
 
-**YieldShell MCP** solves this by keeping normal foreground semantics for fast commands, then automatically promoting long-running commands into managed background processes after a delay (`yield_ms`, default: 30 seconds).
+**YieldShell MCP** solves this by keeping normal foreground semantics for fast
+commands, then automatically promoting long-running commands into managed
+background executions after a delay (`yield_ms`, default: 30 seconds).
 
 ```mermaid
 graph TD
-    A[exec_command] --> B["Wait for yield_ms (default: 30s)"]
-    B --> C{Is process still running?}
-    C -->|Yes| D["backgrounded<br>Returns process_id"]
+    A[execute] --> B["Wait for yield_ms (default: 30s)"]
+    B --> C{Is execution still running?}
+    C -->|Yes| D["backgrounded<br>Returns execution_id"]
     C -->|No| E["completed<br>Returns full output"]
 ```
 
 - **Fast Commands** (e.g., `echo hello`, `ls`): Complete instantly, returning the output immediately.
-- **Long-Running Commands** (e.g., `npm run dev`, `docker build`, `sleep 60`): Automatically yield control back to the agent with a `process_id` and a snapshot of initial output, letting the agent decide when to `read`, `wait`, or `stop` the process.
+- **Long-Running Commands** (e.g., `npm run dev`, `docker build`, `sleep 60`):
+  Automatically yield control back to the agent with an `execution_id` and a
+  snapshot of initial output, letting the agent decide when to `read`, `wait`,
+  or `stop` the execution.
 
 ---
 
@@ -135,12 +141,19 @@ Add to your OpenCode MCP settings:
 }
 ```
 
+These client command and environment snippets are unchanged in 1.0; the
+breaking changes affect tool calls and response fields, not server launch
+configuration.
+
 ---
 
 ## Tool Reference
 
-### `exec`
-Execute a shell command. If the command runs longer than `yield_ms`, it yields a `process_id` and runs in the background.
+### `execute`
+Execute a shell command. If it runs longer than `yield_ms`, the execution moves
+to the background. Addressable responses include an opaque `execution_id`;
+clients must pass it through unchanged to lifecycle tools. `process_id` is the
+numeric OS PID of the initial shell and is not a lifecycle handle.
 
 * **Parameters**:
   * `command` (string, **required**): The command string to execute in the shell.
@@ -152,7 +165,7 @@ Execute a shell command. If the command runs longer than `yield_ms`, it yields a
   * `shell` (string, optional): Shell executable used to run the command. Defaults to the platform shell. Explicit shells are checked by the same allow/deny command policy.
   * `stdin` (string, optional): Initial text input written to standard input immediately after spawning.
   * `close_stdin` (boolean, default: `true`): Close standard input after the initial input is written. Set to `false` when follow-up `write` calls are expected.
-  * `name` (string, optional): A human-readable label/name to identify this process.
+  * `name` (string, optional): A human-readable label for this execution.
   * `yield_ms` (integer, optional): Milliseconds to wait before yielding execution to background. Both omitted and explicit values are clamped to the lesser of `YIELDSHELL_MAX_YIELD_MS` and the transport-safe 55,000ms ceiling. Defaults to `YIELDSHELL_DEFAULT_YIELD_MS` (30,000ms).
   * `timeout_ms` (integer, optional): Total execution runtime limit in milliseconds. Process is terminated if it runs longer than this. Defaults to `YIELDSHELL_DEFAULT_TIMEOUT_MS` (3,600,000ms). Pass `0` explicitly for unlimited execution.
   * `max_output_bytes` (integer, optional): Maximum bytes returned in total across both response streams. Subject to the `YIELDSHELL_MAX_OUTPUT_BYTES` cap. This bounds the response only — retention is controlled separately by `YIELDSHELL_MAX_BUFFER_BYTES`, so output withheld here stays readable via `read`.
@@ -175,37 +188,52 @@ Execute a shell command. If the command runs longer than `yield_ms`, it yields a
   * Inline code execution: prefer writing the content to a reviewable workspace file (for example `scripts/migrate.sql` or `tools/build.sh`) and run it in a small, inspectable step. Declaring `side_effects=["RUNS_INLINE_CODE"]` is rejected under the default policy; operators can clear that default with `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS=,`.
 
 * **Output Statuses**:
-  * Every status returns the cursor fields described under [Byte Cursors & Incremental Reads](#byte-cursors--incremental-reads): `start_seq`, `next_seq`, `latest_seq`, `capped`, and `evicted`. The inline snapshot advances the process's server-side read cursor, so a following `read` or `wait` continues after it rather than repeating it.
-  * `completed`: Process finished within `yield_ms`. Returns exit code, stdout, and stderr. If output was withheld and terminal-process retention is enabled, it also returns `process_id` so the remainder can be inspected with `read`.
-  * `backgrounded`: Process auto-yielded. Returns `process_id`, `pid`, a snapshot of initial stdout/stderr, `duration_ms`, the cursor fields, and a `message` string describing that the process is running in the background.
-  * `timed_out`: Process exceeded `timeout_ms` and was terminated.
-  * `stopped`: Process was explicitly terminated.
-  * `failed_to_start`: Command could not be spawned (e.g., bad directory or policy violation).
+  * Every status returns the cursor fields described under [Byte Cursors & Incremental Reads](#byte-cursors--incremental-reads): `start_seq`, `next_seq`, `latest_seq`, `capped`, and `evicted`. The inline snapshot advances the execution's server-side read cursor, so a following `read` or `wait` continues after it rather than repeating it.
+  * Every retained result (`completed`, `backgrounded`, `timed_out`, `stopped`, or `failed`) returns `execution_id` and, when available, the initial shell's numeric `process_id`.
+  * `completed`: Execution finished within `yield_ms`. Returns exit code, stdout, and stderr; retained output remains addressable with `execution_id`.
+  * `backgrounded`: Execution auto-yielded. Returns both identifiers, a snapshot of initial stdout/stderr, `duration_ms`, cursor fields, and a lifecycle-tool hint.
+  * `timed_out`: Execution exceeded `timeout_ms` and its process group was terminated.
+  * `stopped`: Execution was explicitly terminated.
+  * `failed_to_start`: The command could not create a managed execution (for example, because of a bad directory or policy violation). This outcome is not addressable and may omit both identifiers.
   * `failed`: An internal execution error occurred.
-  * If initial `stdin` delivery fails, responses for the retained process include
+  * If initial `stdin` delivery fails, responses for the retained execution include
     `stdin_error` with the transport error. Initial delivery runs as tracked
     background work so pipe backpressure does not delay auto-yielding.
 
+Example background response (cursor/output fields abbreviated):
+
+```json
+{
+  "status": "backgrounded",
+  "execution_id": "a97e81c9034f",
+  "process_id": 42137,
+  "stdout": "",
+  "stderr": "",
+  "next_seq": 1,
+  "message": "Execution is running in the background. Use read, wait, or stop with execution_id."
+}
+```
+
 ### `read`
-Read stdout and/or stderr output from a running or completed background process.
+Read stdout and/or stderr from a running or completed execution.
 
 * **Parameters**:
-  * `process_id` (string, **required**): Unique identifier of the process.
+  * `execution_id` (string, **required**): Opaque execution handle returned by `execute`; pass it through unchanged.
   * `since_seq` (integer, optional): Byte-position cursor returned as `next_seq` by the previous read. Enables lossless incremental log polling. When omitted, the read resumes from the server-side cursor instead (see [Byte Cursors & Incremental Reads](#byte-cursors--incremental-reads)); pass `since_seq=1` to re-read from the beginning.
   * `max_output_bytes` (integer, optional): Clamps total output returned across the selected streams. Defaults to the server cap.
   * `streams` (string, default: `"both"`): The streams to read. Options: `"both"`, `"stdout"`, or `"stderr"`.
   * `tail_lines` (integer, optional): Return only the newest N lines instead of reading forward. Useful for monitoring a noisy build or test run without paging through it. Mutually exclusive with `since_seq`; must be positive. If the requested tail exceeds `max_output_bytes`, the newest bytes are kept rather than the oldest.
 
 * **Returns**:
-  * `process_id`, `status`, `exit_code`, `signal`, and `stdin_error` when initial input delivery failed. `stdout` and `stderr` text are included based on the `streams` filter — `"both"` includes both, `"stdout"` includes only `stdout`, and `"stderr"` includes only `stderr`.
+  * `execution_id`, `status`, `exit_code`, `signal`, and `stdin_error` when initial input delivery failed. `stdout` and `stderr` text are included based on the `streams` filter — `"both"` includes both, `"stdout"` includes only `stdout`, and `"stderr"` includes only `stderr`.
   * Cursor fields: `start_seq` (position of the first byte returned), `next_seq` (cursor to use in the next `since_seq` read), and `latest_seq` (how far output has advanced overall — when it exceeds `next_seq`, more is waiting).
   * Withheld-output flags: `capped` means more output is available and reading again continues from `next_seq`; `evicted` means output fell out of the ring buffer before it was read and cannot be recovered. When either is set, a `hint` field names the concrete follow-up call.
 
 ### `write`
-Write text input to the standard input (`stdin`) of a running process.
+Write text input to the standard input (`stdin`) of a running execution.
 
 * **Parameters**:
-  * `process_id` (string, **required**): Unique identifier of the process.
+  * `execution_id` (string, **required**): Opaque execution handle returned by `execute`; pass it through unchanged.
   * `input` (string, **required**): Text input to write.
   * `newline` (boolean, default: `false`): If `true`, appends `\n` to the input.
   * `close_stdin` (boolean, default: `false`): Close standard input after this write, delivering EOF to the process.
@@ -213,11 +241,11 @@ Write text input to the standard input (`stdin`) of a running process.
   request ceiling and return `ok: false` with an error.
 
 ### `wait`
-Block execution until the process exits or the wait timeout expires. This allows the LLM to pause and await completion without spawning a new execution loop.
+Block until an execution exits or the wait timeout expires.
 
 * **Parameters**:
-  * `process_id` (string, **required**): Unique identifier of the process.
-  * `timeout_ms` (integer, default: `55000`): Maximum time to wait. Never terminates the process.
+  * `execution_id` (string, **required**): Opaque execution handle returned by `execute`; pass it through unchanged.
+  * `timeout_ms` (integer, default: `55000`): Maximum time to wait. Never stops the execution.
   * `max_output_bytes` (integer, optional): Maximum total output bytes to return across stdout and stderr.
   * `since_seq` (integer, optional): Byte-position cursor from a previous response. When omitted, `wait` resumes from the server-side cursor, so polling in a loop returns each byte exactly once without any cursor bookkeeping.
   * `tail_lines` (integer, optional): Return only the newest N lines. Mutually exclusive with `since_seq`.
@@ -227,7 +255,7 @@ Block execution until the process exits or the wait timeout expires. This allows
   * `waited_ms`: time actually spent waiting.
   * `max_wait_ms`: the effective budget after capping, so a clamped request is visible rather than silent.
 
-* **Important**: If the wait timeout expires, `wait` returns the current status but **does not kill** the process. It continues running in the background.
+* **Important**: If the wait timeout expires, `wait` returns the current status but **does not stop** the execution. It continues running in the background.
 * The effective wait duration is capped at 55 seconds to stay well under typical MCP request timeouts, even if a larger `timeout_ms` is requested. The response reports that cap in `max_wait_ms`.
 * `wait` treats the managed process group disappearing as completion. If the tracked shell exits while descendants in its process group remain alive, the record continues to report `running`. For normal process-group completion, stdout/stderr are drained before the response is returned. Final drain waits are bounded so inherited pipes cannot block a request indefinitely.
 
@@ -237,45 +265,63 @@ Three separate timers control different things. Only one of them ever terminates
 
 | Parameter | Meaning | Terminates the process? | Default | Effective cap |
 | :--- | :--- | :--- | :--- | :--- |
-| `exec(yield_ms)` | How long `exec` stays inline before handing back a `process_id` and letting the command continue in the background. | No | 30,000ms | Lesser of `YIELDSHELL_MAX_YIELD_MS` and 55,000ms |
-| `exec(timeout_ms)` | Total execution limit. On expiry the process group is sent `SIGTERM`, then `SIGKILL`, and the status becomes `timed_out`. | **Yes** | 3,600,000ms | None (`0` means unlimited) |
+| `execute(yield_ms)` | How long `execute` stays inline before handing back an `execution_id` and letting the command continue in the background. | No | 30,000ms | Lesser of `YIELDSHELL_MAX_YIELD_MS` and 55,000ms |
+| `execute(timeout_ms)` | Total execution limit. On expiry the process group is sent `SIGTERM`, then `SIGKILL`, and the status becomes `timed_out`. | **Yes** | 3,600,000ms | None (`0` means unlimited) |
 | `wait(timeout_ms)` | Maximum time a single `wait` call blocks. On expiry it returns `wait_result: "deadline_reached"` and the process keeps running. | No | 55,000ms | 55,000ms |
 
 If `wait` returns with `status: "running"`, check `wait_result`: `"deadline_reached"` means the wait budget expired while the tracked shell or one of its descendants was still alive. The process keeps running and can be polled again.
 
 ### `stop`
-Gracefully terminate or force kill a running process.
+Gracefully terminate or force kill a running execution.
 
 * **Parameters**:
-  * `process_id` (string, **required**): Unique identifier of the process.
+  * `execution_id` (string, **required**): Opaque execution handle returned by `execute`; pass it through unchanged.
   * `signal` (string, default: `"SIGTERM"`): OS signal to send (e.g. `SIGTERM`, `SIGKILL`, `SIGINT`). Invalid names are rejected without stopping the process. Valid names are ignored on Windows.
   * `force_after_ms` (integer, default: `10000`): Grace period before escalating to force kill (`SIGKILL`). It is clamped below the transport-safe 55-second request ceiling so force-kill observation, final output drain, and subprocess reaping still fit within the request.
 
 ### `ps`
-List all managed processes.
+List managed executions, including retained terminal records.
 
-Terminal records are retained temporarily for inspection. Before each otherwise valid `exec` spawn, records older than `YIELDSHELL_PROCESS_RETENTION_MS` are removed and the remaining terminal set is reduced to `YIELDSHELL_MAX_RETAINED_PROCESSES`, oldest first. Running records are never automatically removed. If the shell exits but its process group still has live descendants, status remains `running` until descendants stop. Reaped IDs disappear from `ps` and become unknown to `read`, `wait`, `write`, and `stop`.
+Terminal records are retained temporarily for inspection. Before each otherwise valid `execute` spawn, records older than `YIELDSHELL_PROCESS_RETENTION_MS` are removed and the remaining terminal set is reduced to `YIELDSHELL_MAX_RETAINED_PROCESSES`, oldest first. Running records are never automatically removed. If the shell exits but its process group still has live descendants, status remains `running` until descendants stop. Reaped IDs disappear from `ps` and become unknown to `read`, `wait`, `write`, and `stop`.
 
 * **Parameters**:
-  * `include_completed` (boolean, default: `true`): If `false`, finished/stopped processes are excluded from the output.
+  * `include_completed` (boolean, default: `true`): If `false`, terminal executions are excluded.
   * `limit` (integer, default: `50`): Maximum number of entries.
-* **Returns**: `processes` — a list of process summary objects, each containing: `process_id`, `pid`, `name`, `command`, `cwd`, `status`, `exit_code`, `signal`, `started_at`, `ended_at`, `duration_ms`, `stdout_bytes`, `stderr_bytes`, and `stdin_error` (`null` unless initial input delivery failed).
+* **Returns**: `executions` — a list of execution summaries. Each contains opaque `execution_id`, numeric OS `process_id` (or `null` if unavailable), `name`, `command`, `cwd`, `status`, `exit_code`, `signal`, `started_at`, `ended_at`, `duration_ms`, `stdout_bytes`, `stderr_bytes`, and `stdin_error`.
 * Activity fields help distinguish a genuine hang from quiet work:
   * `last_output_at`: wall-clock time output last arrived on either stream, or `null` if none has.
   * `idle_ms`: milliseconds since that moment, or `null` if no output has arrived. A large and growing `idle_ms` on a `running` process is the signal that it may be stuck.
-  * `latest_seq`: the process-wide cursor position just past the newest captured byte. Comparing it to a `next_seq` you hold shows how much output is waiting.
+  * `latest_seq`: the execution-wide cursor position just past the newest captured byte. Comparing it to a `next_seq` you hold shows how much output is waiting.
+
+```json
+{
+  "executions": [
+    {
+      "execution_id": "a97e81c9034f",
+      "process_id": 42137,
+      "status": "running",
+      "idle_ms": 125.4,
+      "latest_seq": 2049
+    }
+  ]
+}
+```
 
 ### Error Responses
 
-All tools that accept a `process_id` parameter return a structured error dict when the ID is unknown, e.g. `{"process_id": "proc_abc123", "error": "Unknown process_id: proc_abc123"}`. Tools that accept `process_id` always include it in the response alongside the error.
+All tools that accept an `execution_id` return a structured error when the
+opaque handle is unknown, for example:
+`{"execution_id": "a97e81c9034f", "error": "Unknown execution_id: a97e81c9034f"}`.
+The response echoes `execution_id`; a numeric `process_id` is not accepted as
+a substitute.
 
 ### `cleanup`
-Prune completed, stopped, timed-out, and failed process records to free memory.
+Prune completed, stopped, timed-out, and failed execution records.
 
 * **Parameters**:
-  * `completed_older_than_ms` (non-negative integer, default: `3600000`): Prunes completed processes older than this threshold (1 hour default).
-  * `stopped_older_than_ms` (non-negative integer, default: `3600000`): Prunes stopped, timed-out, or failed processes older than this threshold (1 hour default).
-* **Returns**: `removed` — the count of process records that were pruned. Negative thresholds are rejected without removing records and include an `error` message.
+  * `completed_older_than_ms` (non-negative integer, default: `3600000`): Prunes completed executions older than this threshold (1 hour default).
+  * `stopped_older_than_ms` (non-negative integer, default: `3600000`): Prunes stopped, timed-out, or failed executions older than this threshold (1 hour default).
+* **Returns**: `removed` — the count of execution records pruned. Negative thresholds are rejected without removing records and include an `error` message.
 
 ---
 
@@ -284,8 +330,8 @@ Prune completed, stopped, timed-out, and failed process records to free memory.
 To avoid sending duplicate data over the MCP protocol (which can consume context window space), the server implements a byte-position polling protocol:
 
 1. Every stdout/stderr byte receives a unique position in a cursor shared by both streams. Positions start at 1 and only ever increase.
-2. `read`, `wait`, and `exec` all return `next_seq`, the position immediately after the range covered by the response. A response cap can therefore end safely inside a drain chunk.
-3. **You do not have to track cursors.** A `read` or `wait` with no `since_seq` and no `tail_lines` resumes from where the last such call stopped, then advances a server-side cursor held per process. Polling in a loop therefore returns each byte exactly once. `exec`'s inline snapshot advances the same cursor, so a following `wait` continues after it.
+2. `read`, `wait`, and `execute` all return `next_seq`, the position immediately after the range covered by the response. A response cap can therefore end safely inside a drain chunk.
+3. **You do not have to track cursors.** A `read` or `wait` with no `since_seq` and no `tail_lines` resumes from where the last such call stopped, then advances a server-side cursor held per execution. Polling in a loop therefore returns each byte exactly once. `execute`'s inline snapshot advances the same cursor, so a following `wait` continues after it.
 4. To drive the cursor yourself instead, pass the previous `next_seq` back as `since_seq` and keep the same `streams` selection.
 5. **A cursorless read consumes.** Once output has been delivered, a later cursorless read will not return it again. To inspect output that was already delivered, pass `since_seq=1` to re-read from the beginning, or use `tail_lines`.
 6. Requests that pass `since_seq`, pass `tail_lines`, or narrow `streams` are treated as **out-of-band**: they neither consult nor advance the server-side cursor. This means a peek at the tail or at stderr cannot silently skip output the polling stream has not seen yet.
@@ -297,11 +343,11 @@ To avoid sending duplicate data over the MCP protocol (which can consume context
 
 Cursor boundaries preserve valid UTF-8 characters. If a single character is larger than a very small requested page, that page may exceed `max_output_bytes` by at most three bytes so the cursor can make progress without corrupting the character.
 
-Positions are never reused and never reset. Eviction does not rewind them: it advances the oldest retained position while `next_seq` keeps climbing, so a cursor is safe to hold indefinitely. A cursor pointing at data that has since been evicted is not an error — the read returns data from the earliest retained position onward and sets `evicted` to `true`, and `start_seq` shows where the returned range actually begins. Positions are scoped to one process; a cursor from one `process_id` is meaningless for another.
+Positions are never reused and never reset. Eviction does not rewind them: it advances the oldest retained position while `next_seq` keeps climbing, so a cursor is safe to hold indefinitely. A cursor pointing at data that has since been evicted is not an error — the read returns data from the earliest retained position onward and sets `evicted` to `true`, and `start_seq` shows where the returned range actually begins. Positions are scoped to one execution; a cursor from one `execution_id` is meaningless for another.
 
 Incremental cursors are scoped to the selected `streams` value. Keep the same stream selection while advancing a cursor; switching from `stdout`-only or `stderr`-only polling to another selection can intentionally skip bytes from the previously unselected stream.
 
-When a process exits normally, `exec`/`wait` responses include output drained through stdout/stderr EOF. If a descendant keeps inherited stdout/stderr open after the tracked process exits, the server stops waiting on those inherited pipes to avoid indefinite blocking; output written only by that descendant after the tracked process exits is not part of the managed process result.
+When the initial shell exits normally, `execute`/`wait` responses include output drained through stdout/stderr EOF. If a descendant keeps inherited stdout/stderr open, the server stops waiting on those inherited pipes to avoid indefinite blocking; output written only by that descendant after the shell exits is not part of the managed execution result.
 
 ---
 
@@ -314,12 +360,12 @@ Configure the server by setting these environment variables prior to launch:
 | `YIELDSHELL_DEFAULT_CWD` | Current directory | The fallback working directory for commands. |
 | `YIELDSHELL_ALLOWED_CWDS` | *(none)* | A list of allowed directory paths separated by `os.pathsep` (e.g., `:` on UNIX, `;` on Windows). If set, all command execution paths must resolve inside one of these roots. |
 | `YIELDSHELL_MAX_OUTPUT_BYTES` | `20000` | The default and maximum bytes any single response may return across stdout and stderr. This is a response cap only; it does not limit what is retained. Nonpositive or nonnumeric values use the default. |
-| `YIELDSHELL_MAX_BUFFER_BYTES` | `262144` | Capacity of each per-process stdout/stderr ring buffer. Retention is deliberately larger than one response so `since_seq` cursors and `tail_lines` still resolve after a gap between polls. Raise it for very chatty commands, at a cost of roughly this value × 2 streams × live processes in memory. Nonpositive or nonnumeric values use the default. |
+| `YIELDSHELL_MAX_BUFFER_BYTES` | `262144` | Capacity of each per-execution stdout/stderr ring buffer. Retention is deliberately larger than one response so `since_seq` cursors and `tail_lines` still resolve after a gap between polls. Raise it for very chatty commands, at a cost of roughly this value × 2 streams × live executions in memory. Nonpositive or nonnumeric values use the default. |
 | `YIELDSHELL_MAX_PROCESSES` | `50` | Maximum concurrent live managed process groups, including descendants that outlive a completed shell. Spawning a new command when this limit is reached returns `failed_to_start`. Nonpositive or nonnumeric values use the default. |
 | `YIELDSHELL_DEFAULT_YIELD_MS` | `30000` | Fallback delay before auto-yielding. Effective yields are also capped at 55,000ms. |
 | `YIELDSHELL_MAX_YIELD_MS` | `300000` | Configured maximum for `yield_ms`; the effective maximum is the lesser of this value and 55,000ms. |
 | `YIELDSHELL_DEFAULT_TIMEOUT_MS` | `3600000` | Default hard runtime limit (1 hour). An explicit tool argument of `0` means no limit. |
-| `YIELDSHELL_PROCESS_RETENTION_MS` | `3600000` | Age after which terminal process records are reaped before a valid spawn. Zero requests immediate age-based reaping. Negative or nonnumeric values use the default. |
+| `YIELDSHELL_PROCESS_RETENTION_MS` | `3600000` | Age after which terminal execution records are reaped before a valid spawn. Zero requests immediate age-based reaping. Negative or nonnumeric values use the default. |
 | `YIELDSHELL_MAX_RETAINED_PROCESSES` | `100` | Maximum retained terminal records after age reaping; oldest records are removed first. Zero retains no prior terminal records. Negative or nonnumeric values use the default. Running records are excluded. |
 | `YIELDSHELL_DENY_COMMAND_REGEX` | *(none)* | A regular expression pattern. Commands matching this pattern are blocked before starting. Invalid patterns cause startup to fail with a configuration error naming this variable. |
 | `YIELDSHELL_ALLOW_COMMAND_REGEX` | *(none)* | A regular expression pattern. If set, only commands matching this pattern are permitted. Invalid patterns cause startup to fail with a configuration error naming this variable. |
@@ -331,7 +377,7 @@ Configure the server by setting these environment variables prior to launch:
 ## Security Notes
 
 * **Arbitrary Code Execution**: This server executes shell commands on the host system. Always run the server inside a container, sandbox, or isolated development VM.
-* **Side-Effect Declarations**: Every `exec` call must declare its plausible side-effect categories via `side_effects`. By default, `KILLS_AGENT_PROCESS`, `MODIFIES_OS_SETTINGS`, `MODIFIES_OS_USER_SETTINGS`, `MODIFIES_PROTECTED_FILES`, and `RUNS_INLINE_CODE` are blocked. Operators can adjust the blocklist via `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS` (including cleared to `,` to disable every default). This is an explicit risk signal — it is not a complete sandbox, and LLM under-declaration remains possible.
+* **Side-Effect Declarations**: Every `execute` call must declare its plausible side-effect categories via `side_effects`. By default, `KILLS_AGENT_PROCESS`, `MODIFIES_OS_SETTINGS`, `MODIFIES_OS_USER_SETTINGS`, `MODIFIES_PROTECTED_FILES`, and `RUNS_INLINE_CODE` are blocked. Operators can adjust the blocklist via `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS` (including cleared to `,` to disable every default). This is an explicit risk signal — it is not a complete sandbox, and LLM under-declaration remains possible.
 * **Inline Code Execution**: The `RUNS_INLINE_CODE` default discourages agents from executing code supplied inline to an interpreter or shell (e.g. `python -c`, `node -e`, `ruby -e`, `perl -e`, shell heredocs piped into interpreters, or `curl ... | sh`). The safer pattern is to write the content to a reviewable workspace file and execute it in a small, inspectable step with explicit matching `side_effects`. Operators can override the default to permit the category.
 * **OS User Settings Damage**: `MODIFIES_OS_USER_SETTINGS` covers commands that change user-level configuration such as shell rc files, XDG config directories, dotfiles, or per-user application preferences. This is distinct from `MODIFIES_OS_SETTINGS`, which covers broader OS-level configuration such as systemd units, kernel parameters, `/etc` files, and package manager system config. Blocked by default; operators can override.
 * **Agent Process Termination**: `KILLS_AGENT_PROCESS` covers commands that may terminate the MCP client, agent, or related process running the agent workflow (e.g., `kill` commands targeting the agent PID, or commands that cause the agent to exit). This is distinct from `STOPS_OR_RESTARTS_SERVICES`, which covers OS-level services. Blocked by default; operators can override.
@@ -341,9 +387,35 @@ Configure the server by setting these environment variables prior to launch:
 
 ## Lifecycle and Compatibility
 
-YieldShell gives graceful termination 10 seconds before force-killing, waits up to 5 seconds for a POSIX process group to disappear, and allows up to 3 seconds for final stream draining. On stdio server shutdown, all live managed processes are terminated concurrently using the same bounded graceful/forced policy. Already-terminal records are not changed by shutdown.
+YieldShell gives graceful termination 10 seconds before force-killing, waits up
+to 5 seconds for a POSIX process group to disappear, and allows up to 3 seconds
+for final stream draining. On stdio server shutdown, all live managed
+executions are terminated concurrently using the same bounded graceful/forced
+policy. Already-terminal records are not changed by shutdown.
+
+`execution_id` is an opaque, server-generated string. Clients must pass it
+through unchanged rather than parsing or pattern-matching it. Its current
+shape is an implementation detail, not a client contract.
+
+Current lifecycle defaults are a 30-second auto-yield, one-hour runtime timeout, 55-second effective request-wait and stop-grace ceilings, 10-second default stop grace, automatic terminal-record retention, opt-in streaming output redaction, and shutdown containment. Standard input closes after `execute` by default; callers that need an interactive session must set `close_stdin=false`. Use explicit shorter timing values where lower latency is preferred, and pass `timeout_ms=0` to retain unlimited runtime behavior.
+
+### Migration (0.x → 1.0)
+
+Version 1.0.0 is a clean breaking release. There are no compatibility aliases
+or dual-emitted legacy fields.
+
+| 0.x API | 1.0 API |
+| :--- | :--- |
+| Tool `exec` | Tool `execute` |
+| Managed handle `process_id` (string) | Managed handle `execution_id` (opaque string) |
+| OS field `pid` | OS field `process_id` (integer) |
+| `ps` response key `processes` | `ps` response key `executions` |
+| Assumed ID pattern `^proc_[0-9a-f]{12}$` | No supported pattern; treat `execution_id` as opaque |
 
-Current lifecycle defaults are a 30-second auto-yield, one-hour runtime timeout, 55-second effective request-wait and stop-grace ceilings, 10-second default stop grace, automatic terminal-record retention, opt-in streaming output redaction, and shutdown containment. Standard input closes after `exec` by default; callers that need an interactive session must set `close_stdin=false`. Use explicit shorter timing values where lower latency is preferred, and pass `timeout_ms=0` to retain unlimited runtime behavior.
+The most important migration trap is that `process_id` still exists but now
+means the numeric OS PID. Store `execution_id` from `execute` and pass it
+unchanged to `read`, `write`, `wait`, and `stop`. Calls that send the OS
+`process_id` as the handle fail with `Unknown execution_id`.
 
 ---