dirtywork 0.2.0__tar.gz

dirtywork-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dirt Simple Solutions, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dirtywork-0.2.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: dirtywork
+Version: 0.2.0
+Summary: Agentic tool-use loop harness for local LM Studio models — an expensive-model orchestrator's free local workforce
+Author: Dirt Simple Solutions, LLC
+License: MIT
+Project-URL: Repository, https://github.com/JimboSchneider/dirtywork
+Project-URL: Homepage, https://dirtywork.run
+Keywords: llm,agent,lm-studio,local-llm,coding-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dirtywork
+
+[![CI](https://github.com/JimboSchneider/dirtywork/actions/workflows/ci.yml/badge.svg)](https://github.com/JimboSchneider/dirtywork/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dirtywork.svg)](https://pypi.org/project/dirtywork/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/JimboSchneider/dirtywork/blob/main/LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://github.com/JimboSchneider/dirtywork/blob/main/pyproject.toml)
+
+*Frontier models do the thinking. Local models do the dirty work.*
+
+Runs one coding task against a local LM Studio model in an agentic tool-use
+loop, inside an isolated git worktree. Built to be driven by an orchestrating
+agent (Claude Code, in our case) — the expensive frontier model orchestrates
+and reviews, the free local model grinds. Humans watch with `tail -f`.
+
+**The division of labor:**
+
+| | Role |
+|---|---|
+| Orchestrator (a frontier model, e.g. Claude Code — or you) | Picks the task, invokes `dirtywork`, reviews the worktree diff and transcript, commits/PRs what survives review |
+| Worker (local model, via dirtywork) | Explores the repo, edits files, runs builds/tests — inside a worktree it cannot escape |
+
+Nothing the local model does touches your main checkout, and nothing it
+produces merges without review. Parallelism comes from launching multiple
+processes — LM Studio serves 4 concurrent requests per model.
+
+## Requirements
+
+- macOS/Linux, Python 3.9+ (stdlib only — no venv, no pip deps)
+- [LM Studio](https://lmstudio.ai) serving its OpenAI-compatible API at
+  `localhost:1234` with a tool-calling-capable model loaded. Verified
+  working: `qwen/qwen3-coder-next` (65k context, default) and
+  `mistralai/devstral-small-2-2512` (32k context)
+- The target repo must be a git repo with at least one commit
+
+**Other servers:** anything speaking the OpenAI chat-completions API with tool
+calling should work via `--base-url` (e.g. Ollama at
+`http://localhost:11434/v1`) — but only LM Studio is tested today. Reports
+welcome.
+
+## Install
+
+**pipx (PyPI):**
+
+    pipx install dirtywork
+
+**pipx (straight from GitHub):**
+
+    pipx install git+https://github.com/JimboSchneider/dirtywork
+
+**From source:**
+
+    git clone https://github.com/JimboSchneider/dirtywork
+    cd dirtywork
+    chmod +x bin/dirtywork
+    ln -sf "$PWD/bin/dirtywork" ~/.local/bin/dirtywork
+
+The launcher is self-locating, so this works from any clone location.
+
+## Use
+
+    dirtywork run --repo ~/repos/someproject "Add a unit test for X"
+
+- **Watch a run:** `tail -f` the transcript path printed on stderr.
+- **Review a run:** `git -C <worktree> diff`, read the transcript, run the
+  repo's tests — then commit the branch or discard it.
+- **Discard a run:**
+  `git -C <repo> worktree remove --force <worktree> && git -C <repo> branch -D dirtywork/<slug>`
+
+## How a run works
+
+1. **Preflight** — LM Studio reachable, model loaded, repo valid. Any
+   failure exits 2 with nothing created.
+2. **Worktree** — a fresh worktree at `<repo>/.worktrees/dw-<slug>` on new
+   branch `dirtywork/<slug>`, branched from `--branch-from` (default:
+   repo HEAD). `.worktrees/` is added to the repo's local
+   `.git/info/exclude` automatically. If the repo has a `CLAUDE.md` or
+   `AGENTS.md` at its root, its content is injected into the worker's
+   system prompt so it inherits your conventions.
+3. **The loop** — the model gets six tools (`read_file`, `write_file`,
+   `edit_file`, `list_dir`, `grep`, `bash`) via OpenAI function-calling and
+   works until it replies without calling a tool. Context is budgeted per
+   model (oldest tool results get trimmed first); three consecutive
+   malformed tool calls abort the run.
+4. **No auto-commit** — changes stay uncommitted in the worktree; the
+   transcript lands at `~/.dirtywork/runs/<slug>/transcript.jsonl`
+   (outside the worktree, so it can never pollute the diff).
+
+## Safety model
+
+Guardrails block **accidents, not adversaries** — the post-run review is
+the real gate:
+
+- All file tools are path-confined to the worktree (symlink-safe realpath
+  checks; `.git/` is write-protected against hook injection).
+- `bash` runs cwd-pinned in the worktree with a minimal environment (your
+  shell's tokens/keys are not inherited) and a regex denylist: `sudo`,
+  `git push`, `rm`/`mv`/`chmod`/`chown` on absolute or `~` paths,
+  `cd`/`pushd` escapes, downloads piped to a shell, system-control
+  commands, redirects outside the worktree.
+- Every denylist rejection is logged to the transcript as a
+  `guardrail_block` event, so attempted escapes are visible at review time.
+- Network is allowed (package restores need it); per-command timeout 120s
+  default, 600s max.
+
+Plainly: this is **not a sandbox**. Run it against repos where you'd trust
+yourself to review the diff — because that review is the actual gate.
+
+## Development
+
+    python3 -m pytest              # unit suite (no LM Studio needed)
+    python3 -m pytest -m live -v   # live suite (requires LM Studio running;
+                                   # includes a real end-to-end agent run)
+
+Design docs: `docs/superpowers/specs/2026-08-13-localagent-design.md`
+(architecture and contracts) and
+`docs/superpowers/plans/2026-08-14-localagent.md` (implementation plan).
+
+## The story
+
+dirtywork was designed, built, reviewed, and shipped in one day — by the
+exact orchestrator/worker pattern it implements — and its first production
+run surfaced a real cent-level rounding bug in the invoicing app it was
+pointed at. The full postmortem, including a build-one-yourself recipe:
+[the postmortem](https://github.com/JimboSchneider/dirtywork/blob/main/docs/2026-08-14-building-localagent.md)
+(or read [the designed HTML edition](https://dirtywork.run/building-localagent.html)
+served via Pages).
+
+In August 2026 the project was renamed **dirtywork** — same tool, a name that says what it does.
+
+## Troubleshooting
+
+- **exit 2, "cannot reach LM Studio"** — server not running; check `lms ps`
+  and `curl -s localhost:1234/v1/models`.
+- **exit 2, "model not loaded"** — `lms load <model>` (the error names the
+  loaded models).
+- **status `max_turns` / `timeout`** — the worktree is kept; read the
+  transcript to see where it stalled, salvage what's useful, or re-run with
+  higher limits.
+- **status `context_exhausted`** — the task needed more context than the
+  model's window; split the task or use the larger-context model.
+
+## Machine contract
+
+`dirtywork` is built to be driven by another agent (Claude Code) rather than
+read by a human — the primary consumer parses stdout, not the terminal.
+
+**Flags:**
+
+```
+dirtywork run --repo <path> "<task>"
+    [--model qwen/qwen3-coder-next]   # or mistralai/devstral-small-2-2512
+    [--branch-from <ref>]             # default: repo HEAD
+    [--max-turns 40]
+    [--timeout 1800]                  # whole-run wall clock, seconds
+    [--temperature <f>]               # omitted by default → server preset
+    [--base-url http://localhost:1234/v1]  # LM Studio's OpenAI-compatible endpoint
+```
+
+**stdout:** on any run that gets past preflight, exactly one JSON object is
+printed to stdout (nothing else goes to stdout):
+
+```json
+{
+  "status": "completed",
+  "worktree": "/path/to/repo/.worktrees/dw-<slug>",
+  "branch": "dirtywork/<slug>",
+  "transcript": "/path/to/transcript.jsonl",
+  "turns": 7,
+  "usage": {"prompt_tokens": 0, "completion_tokens": 0},
+  "final_message": "..."
+}
+```
+
+`status` is one of: `completed`, `max_turns`, `timeout`,
+`context_exhausted`, `model_error`, `interrupted`. When the run fails before
+a `RunResult` exists — the LLM client raises, post-worktree setup fails (e.g.
+the transcript can't be created), or any other exception escapes the run
+(status `model_error` in every case) — `turns` is `null` and `usage` is `{}`,
+but `status`, `worktree`, `branch`, and `transcript` are still populated so
+the worktree can be located for salvage.
+
+**Exit codes:**
+
+- `0` — `completed`.
+- `1` — run ended abnormally (`max_turns`, `timeout`, `context_exhausted`,
+  `model_error`, `interrupted`); the worktree and branch are kept for
+  salvage/review. `main` catches every `Exception` the run raises (not just
+  ones the runner itself converts to a status) and reports it as
+  `model_error` via the same JSON contract, so a post-preflight run never
+  tracebacks. (Ctrl-C is a `KeyboardInterrupt`, a `BaseException`, not caught
+  here — but the run loop itself already converts in-loop Ctrl-C to status
+  `interrupted` before it would reach this point.)
+- `2` — preflight or environment error (LM Studio unreachable, model not
+  loaded, `--repo` not a git repo, etc.); nothing is created.
+
+All progress (transcript path, worktree path, `error:`-prefixed messages) is
+written to stderr; watch a live run with `tail -f` on the transcript path.
+
+**Transcript events** (JSONL, one per line): `run_start` (task, repo, model,
+config), `assistant` (text + tool calls), `tool_result` (truncated),
+`guardrail_block`, `run_end` (status, turns, duration, cumulative usage).
+
+## Contributing
+
+Issues and PRs welcome. Ground rules:
+
+- Runtime stays **stdlib-only** — that zero-dependency install is a feature,
+  not an accident. Dev-only dependencies (pytest) are fine.
+- `python3 -m pytest` must be green; if your change touches the model-facing
+  path, run the live suite too (`python3 -m pytest -m live -v`, needs a
+  running LM Studio).
+- Tool functions never raise; the client raises `LLMError` only; stdout is
+  exactly one JSON object post-preflight. These contracts have tests — keep
+  them green.
+
+## License
+
+[MIT](https://github.com/JimboSchneider/dirtywork/blob/main/LICENSE) © 2026 Dirt Simple Solutions, LLC

dirtywork-0.2.0/README.md

@@ -0,0 +1,218 @@
+# dirtywork
+
+[![CI](https://github.com/JimboSchneider/dirtywork/actions/workflows/ci.yml/badge.svg)](https://github.com/JimboSchneider/dirtywork/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dirtywork.svg)](https://pypi.org/project/dirtywork/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/JimboSchneider/dirtywork/blob/main/LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://github.com/JimboSchneider/dirtywork/blob/main/pyproject.toml)
+
+*Frontier models do the thinking. Local models do the dirty work.*
+
+Runs one coding task against a local LM Studio model in an agentic tool-use
+loop, inside an isolated git worktree. Built to be driven by an orchestrating
+agent (Claude Code, in our case) — the expensive frontier model orchestrates
+and reviews, the free local model grinds. Humans watch with `tail -f`.
+
+**The division of labor:**
+
+| | Role |
+|---|---|
+| Orchestrator (a frontier model, e.g. Claude Code — or you) | Picks the task, invokes `dirtywork`, reviews the worktree diff and transcript, commits/PRs what survives review |
+| Worker (local model, via dirtywork) | Explores the repo, edits files, runs builds/tests — inside a worktree it cannot escape |
+
+Nothing the local model does touches your main checkout, and nothing it
+produces merges without review. Parallelism comes from launching multiple
+processes — LM Studio serves 4 concurrent requests per model.
+
+## Requirements
+
+- macOS/Linux, Python 3.9+ (stdlib only — no venv, no pip deps)
+- [LM Studio](https://lmstudio.ai) serving its OpenAI-compatible API at
+  `localhost:1234` with a tool-calling-capable model loaded. Verified
+  working: `qwen/qwen3-coder-next` (65k context, default) and
+  `mistralai/devstral-small-2-2512` (32k context)
+- The target repo must be a git repo with at least one commit
+
+**Other servers:** anything speaking the OpenAI chat-completions API with tool
+calling should work via `--base-url` (e.g. Ollama at
+`http://localhost:11434/v1`) — but only LM Studio is tested today. Reports
+welcome.
+
+## Install
+
+**pipx (PyPI):**
+
+    pipx install dirtywork
+
+**pipx (straight from GitHub):**
+
+    pipx install git+https://github.com/JimboSchneider/dirtywork
+
+**From source:**
+
+    git clone https://github.com/JimboSchneider/dirtywork
+    cd dirtywork
+    chmod +x bin/dirtywork
+    ln -sf "$PWD/bin/dirtywork" ~/.local/bin/dirtywork
+
+The launcher is self-locating, so this works from any clone location.
+
+## Use
+
+    dirtywork run --repo ~/repos/someproject "Add a unit test for X"
+
+- **Watch a run:** `tail -f` the transcript path printed on stderr.
+- **Review a run:** `git -C <worktree> diff`, read the transcript, run the
+  repo's tests — then commit the branch or discard it.
+- **Discard a run:**
+  `git -C <repo> worktree remove --force <worktree> && git -C <repo> branch -D dirtywork/<slug>`
+
+## How a run works
+
+1. **Preflight** — LM Studio reachable, model loaded, repo valid. Any
+   failure exits 2 with nothing created.
+2. **Worktree** — a fresh worktree at `<repo>/.worktrees/dw-<slug>` on new
+   branch `dirtywork/<slug>`, branched from `--branch-from` (default:
+   repo HEAD). `.worktrees/` is added to the repo's local
+   `.git/info/exclude` automatically. If the repo has a `CLAUDE.md` or
+   `AGENTS.md` at its root, its content is injected into the worker's
+   system prompt so it inherits your conventions.
+3. **The loop** — the model gets six tools (`read_file`, `write_file`,
+   `edit_file`, `list_dir`, `grep`, `bash`) via OpenAI function-calling and
+   works until it replies without calling a tool. Context is budgeted per
+   model (oldest tool results get trimmed first); three consecutive
+   malformed tool calls abort the run.
+4. **No auto-commit** — changes stay uncommitted in the worktree; the
+   transcript lands at `~/.dirtywork/runs/<slug>/transcript.jsonl`
+   (outside the worktree, so it can never pollute the diff).
+
+## Safety model
+
+Guardrails block **accidents, not adversaries** — the post-run review is
+the real gate:
+
+- All file tools are path-confined to the worktree (symlink-safe realpath
+  checks; `.git/` is write-protected against hook injection).
+- `bash` runs cwd-pinned in the worktree with a minimal environment (your
+  shell's tokens/keys are not inherited) and a regex denylist: `sudo`,
+  `git push`, `rm`/`mv`/`chmod`/`chown` on absolute or `~` paths,
+  `cd`/`pushd` escapes, downloads piped to a shell, system-control
+  commands, redirects outside the worktree.
+- Every denylist rejection is logged to the transcript as a
+  `guardrail_block` event, so attempted escapes are visible at review time.
+- Network is allowed (package restores need it); per-command timeout 120s
+  default, 600s max.
+
+Plainly: this is **not a sandbox**. Run it against repos where you'd trust
+yourself to review the diff — because that review is the actual gate.
+
+## Development
+
+    python3 -m pytest              # unit suite (no LM Studio needed)
+    python3 -m pytest -m live -v   # live suite (requires LM Studio running;
+                                   # includes a real end-to-end agent run)
+
+Design docs: `docs/superpowers/specs/2026-08-13-localagent-design.md`
+(architecture and contracts) and
+`docs/superpowers/plans/2026-08-14-localagent.md` (implementation plan).
+
+## The story
+
+dirtywork was designed, built, reviewed, and shipped in one day — by the
+exact orchestrator/worker pattern it implements — and its first production
+run surfaced a real cent-level rounding bug in the invoicing app it was
+pointed at. The full postmortem, including a build-one-yourself recipe:
+[the postmortem](https://github.com/JimboSchneider/dirtywork/blob/main/docs/2026-08-14-building-localagent.md)
+(or read [the designed HTML edition](https://dirtywork.run/building-localagent.html)
+served via Pages).
+
+In August 2026 the project was renamed **dirtywork** — same tool, a name that says what it does.
+
+## Troubleshooting
+
+- **exit 2, "cannot reach LM Studio"** — server not running; check `lms ps`
+  and `curl -s localhost:1234/v1/models`.
+- **exit 2, "model not loaded"** — `lms load <model>` (the error names the
+  loaded models).
+- **status `max_turns` / `timeout`** — the worktree is kept; read the
+  transcript to see where it stalled, salvage what's useful, or re-run with
+  higher limits.
+- **status `context_exhausted`** — the task needed more context than the
+  model's window; split the task or use the larger-context model.
+
+## Machine contract
+
+`dirtywork` is built to be driven by another agent (Claude Code) rather than
+read by a human — the primary consumer parses stdout, not the terminal.
+
+**Flags:**
+
+```
+dirtywork run --repo <path> "<task>"
+    [--model qwen/qwen3-coder-next]   # or mistralai/devstral-small-2-2512
+    [--branch-from <ref>]             # default: repo HEAD
+    [--max-turns 40]
+    [--timeout 1800]                  # whole-run wall clock, seconds
+    [--temperature <f>]               # omitted by default → server preset
+    [--base-url http://localhost:1234/v1]  # LM Studio's OpenAI-compatible endpoint
+```
+
+**stdout:** on any run that gets past preflight, exactly one JSON object is
+printed to stdout (nothing else goes to stdout):
+
+```json
+{
+  "status": "completed",
+  "worktree": "/path/to/repo/.worktrees/dw-<slug>",
+  "branch": "dirtywork/<slug>",
+  "transcript": "/path/to/transcript.jsonl",
+  "turns": 7,
+  "usage": {"prompt_tokens": 0, "completion_tokens": 0},
+  "final_message": "..."
+}
+```
+
+`status` is one of: `completed`, `max_turns`, `timeout`,
+`context_exhausted`, `model_error`, `interrupted`. When the run fails before
+a `RunResult` exists — the LLM client raises, post-worktree setup fails (e.g.
+the transcript can't be created), or any other exception escapes the run
+(status `model_error` in every case) — `turns` is `null` and `usage` is `{}`,
+but `status`, `worktree`, `branch`, and `transcript` are still populated so
+the worktree can be located for salvage.
+
+**Exit codes:**
+
+- `0` — `completed`.
+- `1` — run ended abnormally (`max_turns`, `timeout`, `context_exhausted`,
+  `model_error`, `interrupted`); the worktree and branch are kept for
+  salvage/review. `main` catches every `Exception` the run raises (not just
+  ones the runner itself converts to a status) and reports it as
+  `model_error` via the same JSON contract, so a post-preflight run never
+  tracebacks. (Ctrl-C is a `KeyboardInterrupt`, a `BaseException`, not caught
+  here — but the run loop itself already converts in-loop Ctrl-C to status
+  `interrupted` before it would reach this point.)
+- `2` — preflight or environment error (LM Studio unreachable, model not
+  loaded, `--repo` not a git repo, etc.); nothing is created.
+
+All progress (transcript path, worktree path, `error:`-prefixed messages) is
+written to stderr; watch a live run with `tail -f` on the transcript path.
+
+**Transcript events** (JSONL, one per line): `run_start` (task, repo, model,
+config), `assistant` (text + tool calls), `tool_result` (truncated),
+`guardrail_block`, `run_end` (status, turns, duration, cumulative usage).
+
+## Contributing
+
+Issues and PRs welcome. Ground rules:
+
+- Runtime stays **stdlib-only** — that zero-dependency install is a feature,
+  not an accident. Dev-only dependencies (pytest) are fine.
+- `python3 -m pytest` must be green; if your change touches the model-facing
+  path, run the live suite too (`python3 -m pytest -m live -v`, needs a
+  running LM Studio).
+- Tool functions never raise; the client raises `LLMError` only; stdout is
+  exactly one JSON object post-preflight. These contracts have tests — keep
+  them green.
+
+## License
+
+[MIT](https://github.com/JimboSchneider/dirtywork/blob/main/LICENSE) © 2026 Dirt Simple Solutions, LLC

dirtywork-0.2.0/dirtywork/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

dirtywork-0.2.0/dirtywork/__main__.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .llm import LLMError, LMStudioClient
+from .runner import Runner
+from .tools import ToolExecutor
+from .transcript import Transcript
+from .workspace import (
+    WorkspaceError,
+    create_worktree,
+    ensure_worktrees_excluded,
+    load_repo_context,
+    make_slug,
+    preflight_repo,
+)
+
+RUNS_DIR = Path.home() / ".dirtywork" / "runs"
+DEFAULT_MODEL = "qwen/qwen3-coder-next"
+
+
+def build_system_prompt(worktree: Path, repo_context: str | None) -> str:
+    prompt = f"""You are a coding agent working in a git worktree at {worktree}.
+Complete the task, then reply with a plain-text summary of what you changed and what commands you ran.
+
+Rules:
+- Use edit_file or write_file for ALL file changes. Never modify files via bash (no sed -i, no echo redirects, no heredocs).
+- Paths are relative to the worktree root.
+- Explore before editing: use list_dir, grep, and read_file to understand the code first.
+- Verify your work: run the repo's tests or build via bash before declaring the task complete.
+- Do not run git commit or git branch commands; leave all changes uncommitted for review.
+- When the task is complete, reply WITHOUT calling any tools — that final plain reply ends the run."""
+    if repo_context:
+        prompt += f"\n\nRepository conventions (from the repo's own docs):\n\n{repo_context}"
+    return prompt
+
+
+def _err(msg: str) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+
+
+def main(argv: list | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dirtywork")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    run_p = sub.add_parser("run", help="run one task in an isolated worktree")
+    run_p.add_argument("task")
+    run_p.add_argument("--repo", required=True, type=Path)
+    run_p.add_argument("--model", default=DEFAULT_MODEL)
+    run_p.add_argument("--branch-from", default=None)
+    run_p.add_argument("--max-turns", type=int, default=40)
+    run_p.add_argument("--timeout", type=int, default=1800)
+    run_p.add_argument("--temperature", type=float, default=None)
+    run_p.add_argument("--base-url", default="http://localhost:1234/v1")
+    args = parser.parse_args(argv)
+
+    repo = args.repo.expanduser().resolve()
+
+    # ---- preflight (exit 2, create nothing) ----
+    client = LMStudioClient(base_url=args.base_url)
+    try:
+        preflight_repo(repo)
+        models = client.list_models()
+    except WorkspaceError as e:
+        _err(str(e))
+        return 2
+    except LLMError as e:
+        _err(f"{e}\nIs LM Studio running? Try: lms ps")
+        return 2
+    if args.model not in models:
+        _err(f"model '{args.model}' not loaded (loaded: {', '.join(models) or 'none'}). "
+             f"Load it with: lms load {args.model}")
+        return 2
+
+    # ---- workspace ----
+    slug = make_slug(args.task, datetime.now())
+    try:
+        ensure_worktrees_excluded(repo)
+        worktree = create_worktree(repo, slug, args.branch_from)
+    except WorkspaceError as e:
+        _err(str(e))
+        return 2
+
+    transcript_path = RUNS_DIR / slug / "transcript.jsonl"
+    print(f"transcript: {transcript_path}", file=sys.stderr)
+    print(f"worktree:   {worktree}", file=sys.stderr)
+
+    # ---- run ----
+    # Everything from here on -- Transcript/ToolExecutor/Runner construction,
+    # system-prompt assembly, and the run itself -- is wrapped in one boundary so
+    # the machine contract (exactly one JSON object on stdout, post-preflight)
+    # holds even if a component other than runner.run() blows up.
+    transcript = None
+    try:
+        transcript = Transcript(transcript_path)
+        executor = ToolExecutor(worktree, transcript=transcript)
+        runner = Runner(client, executor, transcript, model=args.model,
+                        max_turns=args.max_turns, timeout=args.timeout,
+                        temperature=args.temperature,
+                        run_info={"repo": str(repo), "worktree": str(worktree)})
+        system_prompt = build_system_prompt(worktree, load_repo_context(worktree))
+        result = runner.run(system_prompt, args.task)
+    except Exception as e:
+        message = str(e) if isinstance(e, LLMError) else f"unexpected error: {e!r}"
+        if transcript is not None:
+            try:
+                transcript.write("run_end", status="model_error", error=message)
+            except Exception:
+                pass
+        _err(message)
+        print(json.dumps({
+            "status": "model_error",
+            "worktree": str(worktree),
+            "branch": f"dirtywork/{slug}",
+            "transcript": str(transcript_path),
+            "turns": None,
+            "usage": {},
+            "final_message": message,
+        }, indent=2))
+        return 1
+    finally:
+        if transcript is not None:
+            try:
+                transcript.close()
+            except Exception:
+                pass
+
+    print(json.dumps({
+        "status": result.status,
+        "worktree": str(worktree),
+        "branch": f"dirtywork/{slug}",
+        "transcript": str(transcript_path),
+        "turns": result.turns,
+        "usage": result.usage,
+        "final_message": result.final_message,
+    }, indent=2))
+    return 0 if result.status == "completed" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())