hausfold-scruff 1.0.0__tar.gz

hausfold_scruff-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+.mypy_cache/
+.pytest_cache/
+.venv/

hausfold_scruff-1.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: hausfold-scruff
+Version: 1.0.0
+Summary: Python SDK for scruff, the worktree-lifecycle substrate. Shells out to the scruff binary; async-first so it drops into a FastAPI/asyncio backend or a script equally.
+Project-URL: Repository, https://github.com/hausfold/scruff
+Author: hausfold
+License: Apache-2.0
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hausfold-scruff (Python SDK)
+
+A thin Python client over the [`scruff`](../../README.md) binary — the
+worktree-lifecycle substrate for parallel coding agents. scruff has no daemon,
+so this SDK shells out to it (`asyncio.create_subprocess_exec` + `--json`,
+`watch --json` for a live NDJSON stream).
+
+Async-first: `watch()` is naturally a stream. A sync script can still call
+every method via `asyncio.run(...)`.
+
+Import name is `scruff`; the package on PyPI is `hausfold-scruff`.
+
+## Install
+
+```
+pip install hausfold-scruff
+# or: uv add hausfold-scruff
+```
+
+For local development against this repo instead: `pip install -e sdk/python`.
+
+`scruff` itself must be on `PATH`, or pass `ScruffClientOptions(bin="/path/to/scruff")`.
+
+## Two shapes of usage
+
+**Programmatic.** Every `ScruffClient` method except the two ending in
+`_interactive` captures the child's stdout and returns — safe to call from
+a server with many concurrent sessions.
+
+```python
+import asyncio
+from scruff import ScruffClient
+
+async def main() -> None:
+    scruff = ScruffClient()
+
+    envelope = await scruff.list()
+    for lane in envelope.lanes:
+        # occupied/dirty are `bool | None`: None means "not determined",
+        # never coerce it to False.
+        print(lane.name, lane.state, lane.occupied)
+
+    # Create a lane WITHOUT attaching an agent to it — the primitive an
+    # orchestrator wants. child/spawn only ever print the new path.
+    lane_dir = await scruff.child("/path/to/some-repo", "task-42")
+    # ...now launch YOUR OWN agent process against lane_dir.
+
+asyncio.run(main())
+```
+
+```python
+# Live updates instead of polling — created/parked/resumed/reaped/changed.
+async for line in scruff.watch():
+    if line.kind == "created" and line.lane is not None:
+        notify_ui(line.lane)
+
+# Or scoped to the one lane this session holds — no hello/ready framing,
+# and nothing about anybody else's lanes.
+async for event in scruff.watch_lane(lane_dir):
+    if event.kind == "reaped":
+        end_session()
+```
+
+**Interactive.** `new_interactive` / `resume_interactive` inherit the
+calling process's stdio, so when scruff execs the configured agent client
+(`claude`, `codex`, `opencode`, `pi`) it takes over the real terminal — same as
+running `scruff new` by hand — and control returns to you when that session
+ends.
+
+```python
+# A terminal app, run in an actual TTY:
+await scruff.new_interactive("task-42")
+# ... the agent owned the screen; you're back here when it exits.
+```
+
+**Do not call `new_interactive` from a server** — `scruff new` execs the
+agent client unconditionally, without checking for a TTY, so piped stdio
+blocks forever. Use `resume()` instead: it detects piped stdout and prints
+the reopen command as text rather than exec'ing.
+
+## Holding a session open: leases
+
+scruff's sweep (`reap`) needs to know a checkout is in use. On a human's
+machine, `lsof` answers that; a server has no pane or shell cwd'd anywhere,
+so it says so itself with a lease:
+
+```python
+lease = await scruff.lease(lane_dir)  # refreshes on an interval, < the 90s TTL
+# ... serve the session ...
+await lease.release()
+```
+
+Pass `pid=` instead when the lease should track a real local process — the
+OS then drops it the instant that pid dies, no refresh loop needed.
+
+A lease can only **save** a lane from `reap`, never condemn one — "nobody
+leased it" isn't proof nobody's there.
+
+`scruff.lease(...)` is a coroutine, so it can await the first heartbeat before
+returning: a failure to take the lease raises immediately instead of
+surfacing on the next refresh or release call.
+
+## `watch()` cleanup
+
+`watch()` returns an async generator; stop consuming (`break`, or
+`.aclose()`) to kill the underlying process. Async generators aren't
+guaranteed to close promptly when they go out of scope — wrap long-lived use
+in `contextlib.aclosing()` to tear down the subprocess deterministically:
+
+```python
+from contextlib import aclosing
+
+async with aclosing(scruff.watch()) as stream:
+    async for line in stream:
+        ...
+```
+
+## Types for a frontend
+
+`scruff.types` has no runtime dependencies beyond the standard library.
+Import just the dataclasses if you're modeling the same wire shape
+elsewhere:
+
+```python
+from scruff import ScruffLane, WatchEvent
+```
+
+## What's NOT here yet
+
+`hook create`/`hook remove` have no wrapper — shell out via `run()` if you
+need them. Types are hand-ported from the Go structs, not generated; if
+scruff's JSON shape drifts from this file, that's a bug here.
+
+## Testing
+
+`tests/fake-scruff.sh` stands in for the real binary so tests don't need a Go
+build.
+
+```
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+mypy src
+```

hausfold_scruff-1.0.0/README.md

@@ -0,0 +1,144 @@
+# hausfold-scruff (Python SDK)
+
+A thin Python client over the [`scruff`](../../README.md) binary — the
+worktree-lifecycle substrate for parallel coding agents. scruff has no daemon,
+so this SDK shells out to it (`asyncio.create_subprocess_exec` + `--json`,
+`watch --json` for a live NDJSON stream).
+
+Async-first: `watch()` is naturally a stream. A sync script can still call
+every method via `asyncio.run(...)`.
+
+Import name is `scruff`; the package on PyPI is `hausfold-scruff`.
+
+## Install
+
+```
+pip install hausfold-scruff
+# or: uv add hausfold-scruff
+```
+
+For local development against this repo instead: `pip install -e sdk/python`.
+
+`scruff` itself must be on `PATH`, or pass `ScruffClientOptions(bin="/path/to/scruff")`.
+
+## Two shapes of usage
+
+**Programmatic.** Every `ScruffClient` method except the two ending in
+`_interactive` captures the child's stdout and returns — safe to call from
+a server with many concurrent sessions.
+
+```python
+import asyncio
+from scruff import ScruffClient
+
+async def main() -> None:
+    scruff = ScruffClient()
+
+    envelope = await scruff.list()
+    for lane in envelope.lanes:
+        # occupied/dirty are `bool | None`: None means "not determined",
+        # never coerce it to False.
+        print(lane.name, lane.state, lane.occupied)
+
+    # Create a lane WITHOUT attaching an agent to it — the primitive an
+    # orchestrator wants. child/spawn only ever print the new path.
+    lane_dir = await scruff.child("/path/to/some-repo", "task-42")
+    # ...now launch YOUR OWN agent process against lane_dir.
+
+asyncio.run(main())
+```
+
+```python
+# Live updates instead of polling — created/parked/resumed/reaped/changed.
+async for line in scruff.watch():
+    if line.kind == "created" and line.lane is not None:
+        notify_ui(line.lane)
+
+# Or scoped to the one lane this session holds — no hello/ready framing,
+# and nothing about anybody else's lanes.
+async for event in scruff.watch_lane(lane_dir):
+    if event.kind == "reaped":
+        end_session()
+```
+
+**Interactive.** `new_interactive` / `resume_interactive` inherit the
+calling process's stdio, so when scruff execs the configured agent client
+(`claude`, `codex`, `opencode`, `pi`) it takes over the real terminal — same as
+running `scruff new` by hand — and control returns to you when that session
+ends.
+
+```python
+# A terminal app, run in an actual TTY:
+await scruff.new_interactive("task-42")
+# ... the agent owned the screen; you're back here when it exits.
+```
+
+**Do not call `new_interactive` from a server** — `scruff new` execs the
+agent client unconditionally, without checking for a TTY, so piped stdio
+blocks forever. Use `resume()` instead: it detects piped stdout and prints
+the reopen command as text rather than exec'ing.
+
+## Holding a session open: leases
+
+scruff's sweep (`reap`) needs to know a checkout is in use. On a human's
+machine, `lsof` answers that; a server has no pane or shell cwd'd anywhere,
+so it says so itself with a lease:
+
+```python
+lease = await scruff.lease(lane_dir)  # refreshes on an interval, < the 90s TTL
+# ... serve the session ...
+await lease.release()
+```
+
+Pass `pid=` instead when the lease should track a real local process — the
+OS then drops it the instant that pid dies, no refresh loop needed.
+
+A lease can only **save** a lane from `reap`, never condemn one — "nobody
+leased it" isn't proof nobody's there.
+
+`scruff.lease(...)` is a coroutine, so it can await the first heartbeat before
+returning: a failure to take the lease raises immediately instead of
+surfacing on the next refresh or release call.
+
+## `watch()` cleanup
+
+`watch()` returns an async generator; stop consuming (`break`, or
+`.aclose()`) to kill the underlying process. Async generators aren't
+guaranteed to close promptly when they go out of scope — wrap long-lived use
+in `contextlib.aclosing()` to tear down the subprocess deterministically:
+
+```python
+from contextlib import aclosing
+
+async with aclosing(scruff.watch()) as stream:
+    async for line in stream:
+        ...
+```
+
+## Types for a frontend
+
+`scruff.types` has no runtime dependencies beyond the standard library.
+Import just the dataclasses if you're modeling the same wire shape
+elsewhere:
+
+```python
+from scruff import ScruffLane, WatchEvent
+```
+
+## What's NOT here yet
+
+`hook create`/`hook remove` have no wrapper — shell out via `run()` if you
+need them. Types are hand-ported from the Go structs, not generated; if
+scruff's JSON shape drifts from this file, that's a bug here.
+
+## Testing
+
+`tests/fake-scruff.sh` stands in for the real binary so tests don't need a Go
+build.
+
+```
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+mypy src
+```

hausfold_scruff-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "hausfold-scruff"
+version = "1.0.0"
+description = "Python SDK for scruff, the worktree-lifecycle substrate. Shells out to the scruff binary; async-first so it drops into a FastAPI/asyncio backend or a script equally."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+authors = [{ name = "hausfold" }]
+classifiers = [
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/hausfold/scruff"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.11"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scruff"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

hausfold_scruff-1.0.0/src/scruff/__init__.py

@@ -0,0 +1,47 @@
+from .client import ScruffClient, ScruffClientOptions, Lease
+from .errors import ScruffError
+from .exec import RunOptions, RunResult, run, run_json
+from .types import (
+    ScruffEnvelope,
+    ScruffExitCode,
+    ScruffLane,
+    LandedInfo,
+    LandedVerdict,
+    LandedVia,
+    LaneState,
+    PostMergeAhead,
+    WatchEvent,
+    WatchEventKind,
+    WatchHello,
+    WatchLine,
+    is_watch_hello,
+    parse_watch_line,
+)
+from .watch import watch_all, watch_lane
+
+__all__ = [
+    "ScruffClient",
+    "ScruffClientOptions",
+    "Lease",
+    "ScruffError",
+    "RunOptions",
+    "RunResult",
+    "run",
+    "run_json",
+    "ScruffEnvelope",
+    "ScruffExitCode",
+    "ScruffLane",
+    "LandedInfo",
+    "LandedVerdict",
+    "LandedVia",
+    "LaneState",
+    "PostMergeAhead",
+    "WatchEvent",
+    "WatchEventKind",
+    "WatchHello",
+    "WatchLine",
+    "is_watch_hello",
+    "parse_watch_line",
+    "watch_all",
+    "watch_lane",
+]

hausfold_scruff-1.0.0/src/scruff/client.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, AsyncGenerator, Optional
+
+from .errors import ScruffError
+from .exec import RunOptions, merged_env, run, run_json
+from .types import ScruffEnvelope, WatchEvent, WatchLine
+from .watch import watch_all, watch_lane
+
+
+@dataclass
+class ScruffClientOptions:
+    # Path to the scruff binary, or a bare name resolved on PATH. Defaults to
+    # "scruff".
+    bin: Optional[str] = None
+    # Working directory every command runs from — most of scruff's commands
+    # are cwd-sensitive (`new`, `park`, a bare `scruff <name>`). Defaults to
+    # this process's own cwd.
+    cwd: Optional[str] = None
+    # Extra environment variables, merged over the current process's env.
+    # Useful for SCRUFF_AGENT, SCRUFF_OCCUPANCY=lease.
+    env: Optional[dict[str, Optional[str]]] = None
+
+
+class ScruffClient:
+    """A thin client over the `scruff` binary. Every method shells out —
+    there is no daemon, no port, no socket (SPEC.md §14.1) — so this class
+    holds nothing but the options each call needs, and is cheap to
+    construct as often as you like.
+
+    Two methods (`new_interactive`, `resume_interactive`) inherit the
+    calling process's stdio and can hand off the terminal to a coding
+    agent; every other method captures output and returns. Mixing them up
+    matters: see each method's docstring.
+    """
+
+    def __init__(self, options: Optional[ScruffClientOptions] = None) -> None:
+        options = options or ScruffClientOptions()
+        self._opts = RunOptions(bin=options.bin, cwd=options.cwd, env=options.env)
+
+    async def list(self) -> ScruffEnvelope:
+        """`scruff --json` / `scruff list --json` — byte-identical (SPEC.md
+        §2.2). The full snapshot: every live/parked lane, across every repo
+        scruff knows about. Poll this for landedness and PR state; use
+        {watch} for everything else, since it's push rather than poll."""
+        data = await run_json(["--json"], self._opts)
+        return ScruffEnvelope._from_json(data)
+
+    def watch(self) -> AsyncGenerator[WatchLine, None]:
+        """`scruff watch --json` as an async iterator of typed lines — a
+        `hello`, then a `sync` burst for every lane already alive, `ready`,
+        then live changes for as long as you keep iterating. Stop
+        iterating (`break`, or `.aclose()`) to kill the underlying
+        process.
+
+        This is the primitive onOpen/onParked/... callback-style APIs are
+        built from (SPEC.md §14.2) — see {watch_lane} for a version scoped
+        to one lane's `path`.
+
+        ```python
+        async for line in scruff.watch():
+            if line.kind == "created":
+                print("new lane:", line.lane.name if line.lane else None)
+        ```
+        """
+        return watch_all(self._opts)
+
+    def watch_lane(self, path: str) -> AsyncGenerator[WatchEvent, None]:
+        """{watch}, filtered to events about ONE lane (`event.lane.path`)
+        and stripped of the `hello`/`ready` framing that names no lane —
+        the shape an embedder holding one session per lane usually wants:
+        "tell me when THIS lane's state changes." A `sync` event for the
+        lane still passes through: it's how a caller that started watching
+        after the lane went live learns it exists at all.
+
+        Compare full paths, not names: names aren't unique across repos,
+        but a checkout path is the registry's own primary key (SPEC.md
+        §2.1).
+
+        The module-level `scruff.watch_lane` does the same thing but takes
+        its own `RunOptions`; this one carries the client's bin/cwd/env.
+        """
+        return watch_lane(path, self._opts)
+
+    async def child(self, repo_path: str, name: Optional[str] = None) -> str:
+        """`scruff child <repo> [name]` — a lane on ANOTHER repo, registered
+        as a child of cwd. Prints only the new checkout's path on stdout
+        (SPEC.md §2.3's "only the path" discipline extends here too) and
+        never execs a client, which is what makes it the right primitive
+        for an orchestrator: create the lane, then run your OWN agent
+        process against the path it returns."""
+        args = ["child", repo_path, *([name] if name else [])]
+        result = await run(args, self._opts)
+        return result.stdout.strip()
+
+    async def spawn(self, repo_path: str, name: str, agent: Optional[str] = None) -> str:
+        """`scruff spawn <repo> <name> [agent]` — a named lane for a caller
+        with no pane of its own (a scheduler, a web backend). Like
+        {child}, only ever creates the lane and prints its path; never
+        execs."""
+        args = ["spawn", repo_path, name, *([agent] if agent else [])]
+        result = await run(args, self._opts)
+        return result.stdout.strip()
+
+    async def resume(self, name: str) -> str:
+        """`scruff <name>` / `scruff resume <name>` with stdout captured
+        rather than a terminal — which means the Go binary's own TTY check
+        (`ui.IsTTY`) sees a pipe and, by design, never execs a client. It
+        rebuilds the checkout if needed and returns the human-readable
+        result: either confirmation it's ready, or the exact command to
+        reopen the agent's chat by hand. Safe to call from a server
+        process. For a TUI that wants to actually hand off the terminal,
+        use {resume_interactive} instead."""
+        result = await run(["resume", name], self._opts)
+        return result.stdout
+
+    async def park(self, label: Optional[str] = None) -> None:
+        """`scruff park [label]` — commits the working tree as one `wip:`
+        commit on the current branch. Never touches the shared stash stack
+        (README's "park, not git stash" section) — this is the one safe
+        way for concurrent lanes to set work aside."""
+        await run(["park", *([label] if label else [])], self._opts)
+
+    async def unpark(self) -> None:
+        """`scruff unpark` — reverses the most recent `park`, putting its
+        changes back uncommitted. Raises {ScruffError} with `.refused ==
+        True` if that commit is already pushed (scruff will not rewrite
+        published history) or HEAD isn't a parked commit."""
+        await run(["unpark"], self._opts)
+
+    async def reap(self) -> None:
+        """`scruff reap` — sweeps every LANDED lane nobody is standing in
+        (occupied, per {heartbeat}/`lsof`, always wins). Never removes the
+        checkout scruff is being run from, and never removes a stray."""
+        await run(["reap"], self._opts)
+
+    async def reship(self, name: Optional[str] = None) -> None:
+        """`scruff reship [name]` — pushes a branch that outran its already-
+        merged PR, and opens the follow-up. Raises with `.degraded ==
+        True` if `gh` itself is unavailable."""
+        await run(["reship", *([name] if name else [])], self._opts)
+
+    async def heartbeat(self, path: Optional[str] = None, *, pid: Optional[int] = None) -> None:
+        """`scruff heartbeat [path] [--pid N | --release]` — takes or
+        refreshes the occupancy lease on a checkout (SPEC.md §9.1, §14.2).
+        This is the seam built for exactly this SDK: a program embedding
+        scruff has no pane and no shell cwd'd anywhere, so the lease is the
+        only way `reap` learns a checkout is in use. A lease can only SAVE
+        a lane from the sweep, never condemn one — see {lease} for a
+        self-refreshing wrapper instead of calling this on a timer
+        yourself."""
+        args = ["heartbeat", *([path] if path else [])]
+        if pid is not None:
+            args += ["--pid", str(pid)]
+        await run(args, self._opts)
+
+    async def release_heartbeat(self, path: Optional[str] = None) -> None:
+        """Drops the lease taken by {heartbeat}."""
+        await run(["heartbeat", *([path] if path else []), "--release"], self._opts)
+
+    async def lease(
+        self,
+        path: str,
+        *,
+        pid: Optional[int] = None,
+        refresh_seconds: float = 60.0,
+    ) -> "Lease":
+        """Takes an occupancy lease and holds it for as long as the
+        returned handle is open, refreshing on an interval comfortably
+        under the 90s TTL (`internal/occupancy.TTL`) that applies when
+        there's no pid to watch. This is the primitive an embedder's
+        "session" (a connection, not a cwd — SPEC.md §14.2) should hold
+        from connect to disconnect:
+
+        ```python
+        lease = await scruff.lease(lane_dir)
+        # ... serve the session ...
+        await lease.release()
+        ```
+
+        Pass `pid=` instead when the lease should track a real local
+        process — the kernel then releases it the instant that pid dies,
+        with no refresh loop needed at all, and `refresh_seconds` is
+        ignored.
+
+        Unlike the TS SDK's constructor-based `lease()`, this is a
+        coroutine: Python can await the first heartbeat before returning,
+        so a failure to take the lease raises here rather than silently
+        surfacing on the next refresh or release.
+        """
+        kwargs: dict[str, Any] = {"pid": pid} if pid is not None else {}
+        await self.heartbeat(path, **kwargs)
+        return Lease(self, path, pid=pid, refresh_seconds=refresh_seconds)
+
+    async def new_interactive(self, name: Optional[str] = None, agent: Optional[str] = None) -> None:
+        """`scruff new [name] --open [agent]` with stdio INHERITED from the calling
+        process. scruff execs the configured agent client unconditionally
+        here (unlike `resume`, `new` doesn't check for a TTY) —
+        appropriate for a real terminal app (a TUI) that wants to hand off
+        the screen and get control back when the agent session ends, and
+        WRONG for a server: it will block until the agent process exits,
+        with your stdio attached to whatever the agent expects."""
+        # --open is explicit: bare `scruff new` only prints the lane's path.
+        args = ["new", *([name] if name else []), "--open", *([agent] if agent else [])]
+        await _run_interactive(args, self._opts)
+
+    async def resume_interactive(self, name: str) -> None:
+        """`scruff resume <name>` / `scruff <name>` with stdio INHERITED, so a
+        real terminal's TTY check passes and scruff hands off the screen to
+        the agent client. Same caveat as {new_interactive}: blocks until
+        that session ends."""
+        await _run_interactive(["resume", name], self._opts)
+
+
+async def _run_interactive(args: list[str], opts: RunOptions) -> None:
+    bin_ = opts.bin or "scruff"
+    proc = await asyncio.create_subprocess_exec(
+        bin_,
+        *args,
+        cwd=opts.cwd,
+        env=merged_env(opts.env),
+        # stdin/stdout/stderr default to None, i.e. inherited from this
+        # process — the async equivalent of Node's stdio: "inherit".
+    )
+    code = await proc.wait()
+    if code != 0:
+        raise ScruffError(code, "", [bin_, *args])
+
+
+class Lease:
+    """A held occupancy lease. See {ScruffClient.lease}."""
+
+    def __init__(
+        self,
+        client: ScruffClient,
+        path: str,
+        *,
+        pid: Optional[int],
+        refresh_seconds: float,
+    ) -> None:
+        self._client = client
+        self._path = path
+        self._released = False
+        self._task: Optional["asyncio.Task[None]"] = None
+        if pid is None:
+            self._task = asyncio.create_task(self._refresh_loop(refresh_seconds))
+
+    async def _refresh_loop(self, refresh_seconds: float) -> None:
+        try:
+            while True:
+                await asyncio.sleep(refresh_seconds)
+                try:
+                    await self._client.heartbeat(self._path)
+                except ScruffError:
+                    pass  # best-effort refresh; a miss self-heals on the next tick
+        except asyncio.CancelledError:
+            pass
+
+    async def release(self) -> None:
+        """Drops the lease and stops refreshing it. Safe to call more than
+        once."""
+        if self._released:
+            return
+        self._released = True
+        if self._task is not None:
+            self._task.cancel()
+        await self._client.release_heartbeat(self._path)

hausfold_scruff-1.0.0/src/scruff/errors.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from .types import ScruffExitCode
+
+_LABELS: dict[int, str] = {
+    ScruffExitCode.USAGE: "usage",
+    ScruffExitCode.REFUSED: "refused",
+    ScruffExitCode.DEGRADED: "degraded",
+    ScruffExitCode.CONFLICT: "conflict",
+    ScruffExitCode.LOCKED: "locked",
+}
+
+
+class ScruffError(Exception):
+    """Raised by every SDK call that shells out and gets back a non-zero
+    exit. Carries scruff's actual exit code (SPEC.md §2.4) rather than
+    collapsing it to a generic failure — `err.refused` is how a caller tells
+    "scruff declined to destroy something" from "you asked wrong" (`USAGE`) or
+    "registry locked" (`LOCKED`), and each deserves different handling
+    (retry, surface to a human, or just don't retry).
+    """
+
+    def __init__(self, code: int, stderr: str, command: list[str]) -> None:
+        label = _LABELS.get(code, f"exit {code}")
+        suffix = f" — {stderr.strip()}" if stderr else ""
+        super().__init__(f"scruff {' '.join(command)}: {label}{suffix}")
+        self.code = code
+        self.stderr = stderr
+        self.command = command
+
+    @property
+    def refused(self) -> bool:
+        """`True` when scruff declined for safety (occupied, dirty, or not
+        provably landed) rather than because the call itself was wrong."""
+        return self.code == ScruffExitCode.REFUSED
+
+    @property
+    def degraded(self) -> bool:
+        """`True` when the operation completed but a signal was unavailable
+        (forge down, no `lsof`) — check `warnings` on the envelope for
+        why."""
+        return self.code == ScruffExitCode.DEGRADED

hausfold_scruff-1.0.0/src/scruff/exec.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .errors import ScruffError
+
+
+@dataclass
+class RunOptions:
+    """Options threaded through to every subprocess call."""
+
+    # Path to the scruff binary, or a bare name resolved on PATH. Defaults to
+    # "scruff".
+    bin: Optional[str] = None
+    # Working directory to run scruff from — most commands are cwd-sensitive
+    # (`scruff new`, `scruff park`, a bare `scruff <name>`).
+    cwd: Optional[str] = None
+    # Extra environment variables, merged over the current process's env —
+    # e.g. SCRUFF_AGENT, SCRUFF_OCCUPANCY. A value of None unsets the key rather
+    # than passing the literal string "None" to the child.
+    env: Optional[dict[str, Optional[str]]] = None
+    # Piped to the child's stdin, then the stream is closed. Used by
+    # `scruff hook create`/`remove`, which read JSON off stdin (SPEC.md §2.3).
+    stdin: Optional[str] = None
+
+
+@dataclass
+class RunResult:
+    stdout: str
+    stderr: str
+    code: int
+
+
+def merged_env(env: Optional[dict[str, Optional[str]]]) -> Optional[dict[str, str]]:
+    if env is None:
+        return None
+    merged = dict(os.environ)
+    for key, value in env.items():
+        if value is None:
+            merged.pop(key, None)
+        else:
+            merged[key] = value
+    return merged
+
+
+async def run(args: list[str], opts: Optional[RunOptions] = None) -> RunResult:
+    """Runs one scruff invocation to completion and collects its output. Every
+    non-`--json` scruff command writes human text to stdout on success — this
+    is the primitive `list()`/`watch()` build their typed parsing on top of,
+    and the one lifecycle commands (`new`, `park`, `reap`, ...) use directly,
+    surfacing stdout as a plain string.
+
+    Raises {ScruffError} on a non-zero exit, carrying scruff's exit code
+    (SPEC.md §2.4) rather than collapsing every failure into one shape.
+    """
+    opts = opts or RunOptions()
+    bin_ = opts.bin or "scruff"
+    proc = await asyncio.create_subprocess_exec(
+        bin_,
+        *args,
+        cwd=opts.cwd,
+        env=merged_env(opts.env),
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdin_bytes = opts.stdin.encode() if opts.stdin is not None else b""
+    stdout_bytes, stderr_bytes = await proc.communicate(stdin_bytes)
+    stdout = stdout_bytes.decode()
+    stderr = stderr_bytes.decode()
+    code = proc.returncode if proc.returncode is not None else 1
+
+    if code != 0:
+        raise ScruffError(code, stderr, [bin_, *args])
+    return RunResult(stdout=stdout, stderr=stderr, code=code)
+
+
+async def run_json(args: list[str], opts: Optional[RunOptions] = None) -> Any:
+    """Same as {run}, but parses stdout as JSON — for `--json` commands
+    only. scruff's own contract (README, internal/ui) is "stdout carries the
+    payload, every diagnostic goes to stderr", so this never has to guess
+    which lines are data."""
+    result = await run(args, opts)
+    return json.loads(result.stdout)

hausfold_scruff-1.0.0/src/scruff/types.py

@@ -0,0 +1,216 @@
+# Wire types for scruff's frozen public contracts — SPEC.md §2.2 (`--json`) and
+# §14.3 step 2 (`watch --json`). Hand-ported from the Go source of truth
+# (internal/commands/json.go, internal/commands/watch.go) rather than
+# generated, because scruff has no `go generate` step yet for this — see the
+# SDK README for the drift risk that implies.
+#
+# schema 1 is what's actually implemented today. SPEC.md §2.2's example
+# envelope also shows `pr`, `overlap`, `ahead`, `behind` — those are §0.2/
+# later milestones (`overlap`, forge polling) and are NOT on the wire yet.
+# Do not add them here until json.go does; a field that exists in the type
+# but never arrives on the wire is worse than one that's simply missing.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Literal, Optional, Union
+
+
+class ScruffExitCode(IntEnum):
+    """scruff's exit-code contract (SPEC.md §2.4). REFUSED vs USAGE is the one
+    that matters to a caller: "you asked wrong" vs "I declined to destroy
+    something"."""
+
+    OK = 0
+    USAGE = 1
+    REFUSED = 2
+    DEGRADED = 3
+    CONFLICT = 4
+    LOCKED = 5
+
+
+# Closed set — SPEC.md §2.2: "additions are minor, removals major." Treat an
+# unknown value as opaque, not an error.
+LaneState = Literal["live", "parked", "stray"]
+
+LandedVerdict = Literal["yes", "no", "fresh", "contained"]
+
+LandedVia = Optional[
+    Literal[
+        "never-diverged",
+        "ancestry",
+        "pr-head-oid",
+        "patch-equivalence",
+        "merge-tree-empty",
+    ]
+]
+
+
+@dataclass(frozen=True, slots=True)
+class LandedInfo:
+    verdict: LandedVerdict
+    via: LandedVia
+    confidence: str
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> "LandedInfo":
+        return cls(verdict=d["verdict"], via=d.get("via"), confidence=d["confidence"])
+
+
+@dataclass(frozen=True, slots=True)
+class PostMergeAhead:
+    commits: int
+    # PR number, or 0 when there isn't one — scruff doesn't null this field
+    # today (internal/commands/json.go's jsonPostMerge), unlike `pr` at the
+    # envelope level. Treat 0 as "none" here, not as PR #0.
+    pr: int
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> "PostMergeAhead":
+        return cls(commits=d["commits"], pr=d["pr"])
+
+
+@dataclass(frozen=True, slots=True)
+class ScruffLane:
+    """One lane, in the exact shape `--json` uses for `lanes[]` — the same
+    shape `watch --json` puts on `event.lane`. One schema whether you're
+    reading a snapshot or a stream (SPEC.md §14.1).
+
+    `occupied` and `dirty` are three-state on purpose: `None` means "not
+    determined" (no lsof, no forge, cache miss), which is categorically
+    different from `False`. Every consumer bug in scruff's bash-era statusline
+    came from collapsing that `None` into `False` — do not do that here
+    either.
+    """
+
+    name: str
+    repo: str
+    main: str
+    branch: str
+    path: str
+    parent: str
+    # The client this lane opens (claude | codex | opencode | pi, or whatever
+    # adapters are configured) — never the lane's own identity.
+    agent: str
+    state: LaneState
+    occupied: Optional[bool]
+    dirty: Optional[bool]
+    landed: LandedInfo
+    post_merge_ahead: PostMergeAhead
+    last_commit: str
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> "ScruffLane":
+        return cls(
+            name=d["name"],
+            repo=d["repo"],
+            main=d["main"],
+            branch=d["branch"],
+            path=d["path"],
+            parent=d["parent"],
+            agent=d["agent"],
+            state=d["state"],
+            occupied=d["occupied"],
+            dirty=d["dirty"],
+            landed=LandedInfo._from_json(d["landed"]),
+            post_merge_ahead=PostMergeAhead._from_json(d["post_merge_ahead"]),
+            last_commit=d["last_commit"],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ScruffEnvelope:
+    """The `scruff --json` / `scruff list --json` envelope — byte-identical
+    between the two spellings (SPEC.md §2.2)."""
+
+    scruff: str
+    schema: int
+    lanes: list[ScruffLane]
+    warnings: list[str]
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> "ScruffEnvelope":
+        return cls(
+            scruff=d["scruff"],
+            schema=d["schema"],
+            lanes=[ScruffLane._from_json(lane) for lane in d["lanes"]],
+            warnings=list(d["warnings"]),
+        )
+
+
+# ---------------------------------------------------------------------------
+# `scruff watch --json` — SPEC.md §14.3 step 2, §14.4.
+
+# Closed set, same discipline as LaneState/LandedVerdict: additions are
+# minor, removals major. An unknown kind is noise to ignore, not an error to
+# raise on — that's what lets scruff add `landed`/`source: "forge"` later
+# without breaking every SDK pinned to v1 (SPEC.md §14.4).
+WatchEventKind = Literal[
+    "sync", "ready", "created", "parked", "resumed", "reaped", "changed", "warning"
+]
+
+
+@dataclass(frozen=True, slots=True)
+class WatchHello:
+    """First line of every `watch` stream. A version header, not an event —
+    see `capabilities` for why it carries more than `{scruff, schema}`."""
+
+    kind: Literal["hello"]
+    seq: int
+    scruff: str
+    schema: int
+    # What families of event this scruff build can ever send on this stream.
+    # v1 always sends exactly ["registry"]; a future "forge" entry is how a
+    # consumer learns a landed/post_merge_ahead event kind might show up
+    # without guessing from which kinds happen to have arrived yet.
+    capabilities: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class WatchEvent:
+    """Every line after `hello`. One line, at most one lane — never a
+    batch."""
+
+    kind: WatchEventKind
+    # Monotonic across the WHOLE stream, hello included — lets a consumer
+    # fanning this out over its own transport (e.g. a websocket) detect a
+    # dropped line without scruff knowing anything about that transport.
+    seq: int
+    # RFC3339 UTC. When THIS scruff process observed the change, not
+    # necessarily when it happened at the source. Absent on `hello`.
+    ts: Optional[str] = None
+    # Which provider produced the event. v1 only ever writes "registry";
+    # absent on `ready`, which names no lane and no provider.
+    source: Optional[str] = None
+    # Present on every kind except `ready` and `warning`.
+    lane: Optional[ScruffLane] = None
+    # Present only on `warning` — the same text `warnings[]` carries under
+    # `--json`, pushed here because a stream reader has no envelope to poll.
+    message: Optional[str] = None
+
+
+WatchLine = Union[WatchHello, WatchEvent]
+
+
+def parse_watch_line(d: dict[str, Any]) -> WatchLine:
+    if d["kind"] == "hello":
+        return WatchHello(
+            kind="hello",
+            seq=d["seq"],
+            scruff=d["scruff"],
+            schema=d["schema"],
+            capabilities=list(d["capabilities"]),
+        )
+    return WatchEvent(
+        kind=d["kind"],
+        seq=d["seq"],
+        ts=d.get("ts"),
+        source=d.get("source"),
+        lane=ScruffLane._from_json(d["lane"]) if d.get("lane") is not None else None,
+        message=d.get("message"),
+    )
+
+
+def is_watch_hello(line: WatchLine) -> bool:
+    return isinstance(line, WatchHello)

hausfold_scruff-1.0.0/src/scruff/watch.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import AsyncGenerator, Optional
+
+from .exec import RunOptions, merged_env
+from .types import WatchEvent, WatchLine, parse_watch_line
+
+
+async def watch_all(opts: Optional[RunOptions] = None) -> AsyncGenerator[WatchLine, None]:
+    """`scruff watch --json` as an async iterator of typed lines. One object
+    per NDJSON line on stdout, in order: `hello`, a `sync` burst for every
+    lane already alive, `ready`, then live changes for as long as the
+    process runs (SPEC.md §14.3 step 2).
+
+    The child process is killed when you stop consuming — `break` out of an
+    `async for`, or call `.aclose()` on the generator. Async generators are
+    not guaranteed to be finalized promptly by garbage collection the way
+    CPython's refcounting closes sync generators, so wrap long-lived use in
+    `contextlib.aclosing()` if you want the subprocess torn down
+    deterministically rather than on the next GC pass:
+
+    ```python
+    from contextlib import aclosing
+
+    async with aclosing(scruff.watch()) as stream:
+        async for line in stream:
+            ...
+    ```
+
+    There is no other way to stop it short: `watch` has no built-in end
+    condition, by design (SPEC.md §14).
+    """
+    opts = opts or RunOptions()
+    bin_ = opts.bin or "scruff"
+    proc = await asyncio.create_subprocess_exec(
+        bin_,
+        "watch",
+        "--json",
+        cwd=opts.cwd,
+        env=merged_env(opts.env),
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    assert proc.stdout is not None
+    try:
+        while True:
+            raw = await proc.stdout.readline()
+            if not raw:
+                break
+            line = raw.decode().strip()
+            if not line:
+                continue
+            yield parse_watch_line(json.loads(line))
+    finally:
+        if proc.returncode is None:
+            proc.kill()
+            await proc.wait()
+
+
+async def watch_lane(path: str, opts: Optional[RunOptions] = None) -> AsyncGenerator[WatchEvent, None]:
+    """{watch_all}, filtered to events about one lane (`event.lane.path`)
+    and stripped of the `hello`/`ready` framing that names no lane — the
+    shape an embedder holding one session per lane usually wants: "tell me
+    when THIS lane's state changes."
+
+    A `sync` event for the lane still passes through — it is NOT framing.
+    It's how a caller that started watching after the lane went live learns
+    the lane exists at all, so a match over `event.kind` needs a `sync` arm.
+
+    Compare full paths, not names: names aren't unique across repos, but a
+    checkout path is the registry's own primary key (SPEC.md §2.1).
+    """
+    async for line in watch_all(opts):
+        if isinstance(line, WatchEvent) and line.lane is not None and line.lane.path == path:
+            yield line

hausfold_scruff-1.0.0/tests/fake-scruff.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# A stand-in for the real `scruff` binary, used only by this SDK's own tests.
+# Emits fixed --json / watch --json payloads so the SDK's parsing, process
+# lifecycle and error mapping can be exercised without a Go build.
+#
+# Kept in sync by hand with sdk/ts/test/fake-scruff.sh — same fixture data, so
+# a wire-shape bug shows up identically in both SDKs' test suites.
+set -euo pipefail
+
+case "${1:-}" in
+  --json|list)
+    cat <<'JSON'
+{
+  "scruff": "0.1.0-dev",
+  "schema": 2,
+  "lanes": [
+    {
+      "name": "sparkle",
+      "repo": "hausfold/haus",
+      "main": "/repo/haus",
+      "branch": "worktree-sparkle",
+      "path": "/repo/.scruff/haus/sparkle",
+      "parent": "/repo/haus",
+      "agent": "claude",
+      "state": "live",
+      "occupied": true,
+      "dirty": false,
+      "landed": { "verdict": "no", "via": null, "confidence": "certain" },
+      "post_merge_ahead": { "commits": 0, "pr": 0 },
+      "last_commit": "spec: SDK smoke test fixture"
+    },
+    {
+      "name": "frost",
+      "repo": "hausfold/haus",
+      "main": "/repo/haus",
+      "branch": "worktree-frost",
+      "path": "/repo/.scruff/haus/frost",
+      "parent": "/repo/haus",
+      "agent": "codex",
+      "state": "parked",
+      "occupied": null,
+      "dirty": null,
+      "landed": { "verdict": "contained", "via": "merge-tree-empty", "confidence": "advisory" },
+      "post_merge_ahead": { "commits": 0, "pr": 0 },
+      "last_commit": "park: set aside"
+    }
+  ],
+  "warnings": []
+}
+JSON
+    ;;
+
+  watch)
+    echo '{"kind":"hello","seq":0,"scruff":"0.1.0-dev","schema":2,"capabilities":["registry"]}'
+    echo '{"kind":"sync","seq":1,"ts":"2026-08-07T02:11:04Z","source":"registry","lane":{"name":"sparkle","repo":"hausfold/haus","main":"/repo/haus","branch":"worktree-sparkle","path":"/repo/.scruff/haus/sparkle","parent":"/repo/haus","agent":"claude","state":"live","occupied":true,"dirty":false,"landed":{"verdict":"no","via":null,"confidence":"certain"},"post_merge_ahead":{"commits":0,"pr":0},"last_commit":"c1"}}'
+    echo '{"kind":"ready","seq":2,"ts":"2026-08-07T02:11:04Z"}'
+    sleep 0.05
+    echo '{"kind":"created","seq":3,"ts":"2026-08-07T02:11:05Z","source":"registry","lane":{"name":"fresh","repo":"hausfold/haus","main":"/repo/haus","branch":"worktree-fresh","path":"/repo/.scruff/haus/fresh","parent":"/repo/haus","agent":"claude","state":"live","occupied":true,"dirty":true,"landed":{"verdict":"no","via":null,"confidence":"certain"},"post_merge_ahead":{"commits":0,"pr":0},"last_commit":"c2"}}'
+    # Stay alive until killed, same as the real `watch`.
+    trap 'exit 0' TERM INT
+    while true; do sleep 0.05; done
+    ;;
+
+  child)
+    echo "/repo/.scruff/other/new-lane"
+    ;;
+
+  park)
+    exit 0
+    ;;
+
+  heartbeat)
+    if [[ " $* " == *" --release "* ]]; then
+      echo "released $2" >&2
+    fi
+    exit 0
+    ;;
+
+  reap-refused)
+    echo "refused: occupied" >&2
+    exit 2
+    ;;
+
+  resume)
+    # Mirrors the real resume's non-TTY behaviour: print the reopen command
+    # instead of exec'ing anything, since stdout is a pipe under test.
+    echo "checkout ready. Reopen the claude chat with:"
+    echo "    cd /repo/.scruff/haus/sparkle && claude --resume"
+    ;;
+
+  *)
+    echo "fake-scruff: unhandled args: $*" >&2
+    exit 1
+    ;;
+esac

hausfold_scruff-1.0.0/tests/test_client.py

@@ -0,0 +1,95 @@
+import os
+from contextlib import aclosing
+
+import pytest
+
+from scruff import ScruffClient, ScruffClientOptions, ScruffError
+from scruff.exec import RunOptions, run
+from scruff.watch import watch_lane
+
+FAKE_SCRUFF = os.path.join(os.path.dirname(__file__), "fake-scruff.sh")
+
+
+def client() -> ScruffClient:
+    return ScruffClient(ScruffClientOptions(bin=FAKE_SCRUFF))
+
+
+async def test_list_parses_the_json_envelope_with_nullable_discipline_intact() -> None:
+    envelope = await client().list()
+    assert envelope.schema == 2
+    assert len(envelope.lanes) == 2
+
+    sparkle = envelope.lanes[0]
+    assert sparkle.occupied is True  # True, not falsy-coerced
+    assert sparkle.dirty is False  # False, distinct from None
+
+    frost = envelope.lanes[1]
+    assert frost.occupied is None  # None means "not determined"
+    assert frost.dirty is None
+    assert frost.landed.verdict == "contained"
+
+
+async def test_watch_yields_hello_sync_ready_then_live_changes_and_stops_on_break() -> None:
+    kinds = []
+    async with aclosing(client().watch()) as stream:
+        async for line in stream:
+            kinds.append(line.kind)
+            if line.kind == "created":
+                break
+    assert kinds == ["hello", "sync", "ready", "created"]
+
+
+async def test_watch_lane_filters_to_one_lanes_events_only() -> None:
+    seen = []
+    async with aclosing(watch_lane("/repo/.scruff/haus/fresh", RunOptions(bin=FAKE_SCRUFF))) as stream:
+        async for ev in stream:
+            seen.append(ev.kind)
+            break
+    assert seen == ["created"]
+
+
+async def test_client_watch_lane_filters_the_same_way_on_its_own_options() -> None:
+    seen = []
+    async with aclosing(client().watch_lane("/repo/.scruff/haus/fresh")) as stream:
+        async for ev in stream:
+            seen.append(ev.kind)
+            break
+    assert seen == ["created"]
+
+
+# `sync` names a lane, so it is data, not framing — it's the only way a caller
+# that attached AFTER the lane went live learns the lane exists. Pinned because
+# three docstrings used to claim the opposite.
+async def test_watch_lane_passes_a_lanes_sync_through() -> None:
+    seen = []
+    async with aclosing(client().watch_lane("/repo/.scruff/haus/sparkle")) as stream:
+        async for ev in stream:
+            seen.append(ev.kind)
+            break
+    assert seen == ["sync"]
+
+
+async def test_child_returns_only_the_new_checkout_path() -> None:
+    directory = await client().child("/repo/other")
+    assert directory == "/repo/.scruff/other/new-lane"
+
+
+async def test_resume_captured_stdout_never_execs() -> None:
+    out = await client().resume("sparkle")
+    assert "claude --resume" in out
+
+
+async def test_error_mapping_nonzero_exit_raises_scruff_error_carrying_the_real_exit_code() -> None:
+    with pytest.raises(ScruffError) as exc_info:
+        await run(["reap-refused"], RunOptions(bin=FAKE_SCRUFF))
+    err = exc_info.value
+    assert err.code == 2
+    assert err.refused is True
+    assert "occupied" in err.stderr
+
+
+async def test_lease_release_calls_heartbeat_release() -> None:
+    c = client()
+    lease = await c.lease("/repo/.scruff/haus/sparkle", pid=12345)
+    await lease.release()
+    # No raise: fake-scruff's heartbeat branch accepts --release silently.