tether-sdk 0.2.5__tar.gz → 0.2.6__tar.gz

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/AGENTS.md

@@ -45,7 +45,7 @@ Reviewers and the Team Leader cite the failing line when they reject a change.
 - Sessions do **not** terminate simply because the model emitted a text response without a tool call (small 9B models frequently "think out loud" before acting).
 - A task only completes when the agent explicitly calls `act("done", stdin="<final deliverable>")` (or `act("done '<short answer>'")`), pauses for human/parent input via `act("done --ask", stdin="<question>")` (transitioning the session to `WAITING_INPUT` and releasing the worker process until resumed via `send`), or hits `max_steps`.
 - If the model emits plain text without calling `act`, the harness appends a brief deterministic nudge reminding it to either execute a command or call `done`.
-- After 6 consecutive read-only/verification steps following a change, the harness appends a one-shot `[NUDGE]` to that step's observation reminding the model to call `done` if the task is complete (0 static prompt tokens, #74). Seven reads of one file in a row with no change are a `cycle_stall`, and 4 stall warnings without a change end the session `FAILED` as `Stalled` (#92); `tether stop <id>` terminates a detached worker (#89).
+- After 6 consecutive read-only/verification steps following a change, the harness appends a one-shot `[NUDGE]` to that step's observation reminding the model to call `done` if the task is complete (0 static prompt tokens, #74). Before any change, 12 read-only steps in a row (then every 8 more) append a one-line `[NUDGE]` to make the edit or call `done` (#127). Seven reads of one file in a row with no change are a `cycle_stall`, and 4 stall warnings without a change end the session `FAILED` as `Stalled` (#92); `tether stop <id>` terminates a detached worker (#89).
 - When `verify` gate commands are configured (via `Harness(verify=[...])`, CLI `--verify`, or Skill YAML `verify: [...]`), `Harness.execute_session` deterministically executes each command inside the session's `SandboxPolicy` before allowing `done` to transition to `COMPLETED` (consuming 0 static prompt tokens until a gate fails). A gate that errors instead of failing (sandbox violation, exit 124/126/127) ends the session `FAILED` at once as `gate_error` ("gate misconfigured"), without counting toward the consecutive-failure abort.
 
 ### Rule 4: Progressive `--help` (JIT Schema Disclosure)
@@ -71,7 +71,7 @@ Reviewers and the Team Leader cite the failing line when they reject a change.
   - All `edit` and `bash` paths are canonicalized (`Path.resolve()`) and confined to `workspace_root`.
   - Sensitive files/directories (`.env*`, `.git/config`, `.git/hooks`, `~/.ssh`, `.tether/`) are deterministically protected from mutation or read exfiltration.
   - `bash` subprocesses get an allowlisted environment only (secrets with any name are dropped; opt-in via `TETHER_ENV_PASSTHROUGH`). `web fetch` blocks loopback/private/metadata addresses (SSRF guard). `SandboxPolicy(network=False)` / `--no-network` adds `--unshare-net` (fails closed without `bwrap`; children can only narrow it).
-  - On Linux, `bash` automatically uses **`bwrap` (Bubblewrap) / `unshare`** when available (read-only `/`, hidden `/home` and `/var/tmp` tmpfs (existing `PATH` dirs under them, e.g. `~/.local/bin`, are re-bound read-only so `uv`/`node` still run, #76), `/run` unix sockets such as `docker.sock` masked, read-write bind on `workspace_root` with secret-looking files at any depth (`.env*`, `*.pem`, `*.key`, ...), `.tether/`, `.git/config` and `.git/hooks` masked at the mount level, `PR_SET_NO_NEW_PRIVS`), falling back to a strict deterministic command allowlist/denylist (`rm -rf /`, `sudo`, `dd`, `mkfs`, `chmod 777`, etc. blocked).
+  - On Linux, `bash` automatically uses **`bwrap` (Bubblewrap) / `unshare`** when available (read-only `/`, hidden `/home` and `/var/tmp` tmpfs (existing `PATH` dirs under them, e.g. `~/.local/bin`, are re-bound read-only so `uv`/`node` still run, #76), `/run` unix sockets such as `docker.sock` masked, read-write bind on `workspace_root` with secret-looking files at any depth (`.env*`, `*.pem`, `*.key`, ...), `.tether/`, `.git/config` and `.git/hooks` masked at the mount level, `PR_SET_NO_NEW_PRIVS`), falling back to a strict deterministic command allowlist/denylist (path, `..` and `.env` text rules run only in this fallback, the mounts enforce them under `bwrap`, #125; `.env.example`-style templates are not secrets) (`rm -rf /`, `sudo`, `dd`, `mkfs`, `chmod 777`, etc. blocked).
   - Sub-agents spawned via `agent spawn` strictly inherit or narrow their parent session's `SandboxPolicy` (no privilege escalation).
 
 ### Rule 7: Zero Framework Bloat

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tether-sdk
-Version: 0.2.5
+Version: 0.2.6
 Summary: General-purpose, headless-first LLM-Native micro-harness for small language models
 Project-URL: Homepage, https://github.com/igormcsouza/tether
 Project-URL: Repository, https://github.com/igormcsouza/tether

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/bench/README.md

@@ -4,8 +4,8 @@ Not part of the `tether` package, not run in CI. Use it to onboard a new model o
 release for regressions that deterministic tests cannot see (unit, golden and e2e tests stay the
 gate; see `docs/testing.md`).
 
-Seven tasks in `tasks/<name>/` (workspace in `ws/`, goal in `goal.txt`, hidden tests in `hidden/`):
-`focus` (one exact edit in a distractor-heavy repo, scope-checked), `code-simple`, `code-medium`, `code-hard` (graded by hidden unit tests; editing the visible tests
+Nine tasks in `tasks/<name>/` (workspace in `ws/`, goal in `goal.txt`, hidden tests in `hidden/`):
+`focus` (one exact edit in a distractor-heavy repo, scope-checked), `plan` (an implementation plan, checked for named files, failure handling and tests), `codereview` (eight seeded bugs to find, no edits), `code-simple`, `code-medium`, `code-hard` (graded by hidden unit tests; editing the visible tests
 scores 0), `qa`, `content`, `review` (graded by constraint counts and keyword checks, so they are
 a smoke test for quality, not a judge).
 

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/bench/grade.py

@@ -135,8 +135,49 @@ def _focus(task, ws, result):
     return r
 
 
+def _steps(t):
+    return len(re.findall(r"^\s*\d+[.)]", t, re.M))
+
+
+def _plan(_task, _ws, result):
+    t = result or ""
+    c = {
+        "6-10 numbered steps": 6 <= _steps(t) <= 10,
+        "names client.py": "client.py" in t,
+        "names config.py": "config.py" in t,
+        "names get/post": bool(re.search(r"\bget\b", t)) and bool(re.search(r"\bpost\b", t)),
+        "backoff+jitter": bool(re.search(r"exponential", t, re.I)) and bool(re.search(r"jitter", t, re.I)),
+        "retry settings": bool(re.search(r"max[_ -]?(retries|attempts)|retry[_ -]?(limit|count)", t, re.I)) and bool(re.search(r"base[_ -]?(delay|backoff)|backoff[_ -]?(base|factor)", t, re.I)),
+        "429 and 5xx": "429" in t and bool(re.search(r"5xx|50\d", t)),
+        "not retried (4xx)": bool(re.search(r"4xx|not retr|never retr|do not retry|don't retry|non-retry", t, re.I)),
+        "Retry-After": bool(re.search(r"retry-after", t, re.I)),
+        "tests without network": bool(re.search(r"mock|fake|stub|patch|monkeypatch|inject", t, re.I)) and bool(re.search(r"test", t, re.I)),
+        "idempotency of post": bool(re.search(r"idempot|post.{0,60}(retry|retri)|(retry|retri).{0,60}post", t, re.I)),
+    }
+    return {"score": round(sum(c.values()) / len(c), 3), "pass": sum(c.values()) >= 9, "detail": {"missed": [k for k, v in c.items() if not v]}}
+
+
+BUGS = {
+    "page off-by-one": r"page.{0,200}(off.by.one|number\s*-\s*1|\(number - 1\)|1-based|zero|skips? the first)|(off.by.one|1-based).{0,200}page",
+    "mutable default": r"mutable default|tags=\[\]|default (argument|arg|list)|shared (between|across)",
+    "float money": r"float.{0,120}(money|price|currenc|rounding|precision|decimal)|decimal",
+    "float equality": r"(==|equal).{0,100}(float|0\.0)|is_free|float.{0,60}(compar|equal)|isclose",
+    "sql injection": r"sql.?inject|parameteri[sz]|placeholder|string concat|bind (var|param)",
+    "file not closed": r"(not|never) clos|resource leak|context manager|with open|leak",
+    "keyerror/missing": r"keyerror|missing (key|item|name)|\.get\(|unknown name|not in (the )?(stock|dict)",
+    "split malformed": r"split.{0,100}(more than|exactly|two|malformed|blank|empty|valueerror)|blank line|malformed|empty line|valueerror",
+}
+
+
+def _codereview(_task, _ws, result):
+    t = result or ""
+    hit = {k: bool(re.search(v, t, re.I | re.S)) for k, v in BUGS.items()}
+    must = ["page off-by-one", "mutable default", "sql injection", "file not closed", "keyerror/missing"]
+    return {"score": round(sum(hit.values()) / len(hit), 3), "pass": all(hit[k] for k in must), "detail": {"missed": [k for k, v in hit.items() if not v], "items": _steps(t)}}
+
+
 def grade(task, ws, result):
-    fn = {"qa": _qa, "content": _content, "review": _review, "focus": _focus}.get(task, _code)
+    fn = {"qa": _qa, "content": _content, "review": _review, "focus": _focus, "plan": _plan, "codereview": _codereview}.get(task, _code)
     try:
         return fn(task, ws, result)
     except Exception as e:  # grader bug must never look like a model result

tether_sdk-0.2.6/bench/harness-bench/README.md

@@ -0,0 +1,25 @@
+# Harness-Bench adapter (pilot, not yet run end to end)
+
+[Harness-Bench](https://github.com/Qihoo360/harness-bench) ([paper](https://arxiv.org/abs/2605.27922)) scores
+whole harnesses on 274 offline workflow tasks (plus 26 multimodal) with hidden oracles. This directory holds
+the patch that registers Tether as an eighth harness. It is a way to benchmark, not a Tether feature.
+
+`tether-adapter.patch` applies to harness-bench commit `b8d89634c6f445fcc68ceb6744a59bef6cdf4863`:
+
+```bash
+git clone https://github.com/Qihoo360/harness-bench && cd harness-bench
+git apply /path/to/tether/bench/harness-bench/tether-adapter.patch
+uv sync --extra dev
+export PYTHONPATH=$PWD/src:$PWD/tools:$PWD/tools/task_maintenance
+python tools/run_benchmark.py --base-url "$URL" --model "$MODEL" --harness tether \
+    --tasks 001-meeting-summary --workers 1 --run-root /tmp/hb-run
+```
+
+What the patch adds: `docker/harnesses/tether/` (their toolchain image plus `tether-sdk`, an entrypoint that runs
+`tether run --tools bash,edit` with state kept outside the graded workspace), a `tether` `HarnessSpec`, and a
+`providers.yaml` renderer.
+
+Status (2026-10-23): image builds, `tether run` starts inside the trial container and reaches `ProviderError ...
+ConnectError`, because on the machine used containers cannot reach host ports (`host.docker.internal`, where the
+per-trial model proxy listens). The host firewall must allow the docker bridge to the proxy's ports. No task has
+been scored yet.

tether_sdk-0.2.6/bench/harness-bench/tether-adapter.patch

@@ -0,0 +1,134 @@
+diff --git a/docker/harnesses/tether/Dockerfile b/docker/harnesses/tether/Dockerfile
+new file mode 100644
+index 0000000..d9f3e28
+--- /dev/null
++++ b/docker/harnesses/tether/Dockerfile
+@@ -0,0 +1,45 @@
++FROM python:3.12-slim-bookworm@sha256:d50fb7611f86d04a3b0471b46d7557818d88983fc3136726336b2a4c657aa30b AS task-toolchain
++
++ARG PIP_INDEX_URL
++ARG PIP_EXTRA_INDEX_URL
++ARG PIP_TRUSTED_HOST
++COPY docker/openclaw/requirements.lock /tmp/harnessbench-requirements.lock
++RUN python -m pip install --disable-pip-version-check --no-cache-dir \
++      --requirement /tmp/harnessbench-requirements.lock \
++    && rm /tmp/harnessbench-requirements.lock
++
++FROM python:3.12-slim@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
++
++ARG TETHER_VERSION=0.2.5
++ARG PYPI_INDEX_URL=https://pypi.org/simple
++RUN apt-get update \
++    && apt-get install -y --no-install-recommends bash git ripgrep sqlite3 \
++    && rm -rf /var/lib/apt/lists/*
++
++
++
++RUN useradd --create-home --uid 1000 harness
++COPY --from=task-toolchain /usr/local/ /usr/local/
++COPY docker/openclaw/verify_toolchain.py /opt/harnessbench/verify_toolchain.py
++COPY docker/harnesses/tether/entrypoint.sh /opt/harness/bin/run
++RUN ln -sf /usr/local/bin/python3 /usr/bin/python3 \
++    && python /opt/harnessbench/verify_toolchain.py --python-only \
++    && python -m venv /opt/tether \
++    && /opt/tether/bin/python -m pip install --no-cache-dir \
++        --index-url "${PYPI_INDEX_URL}" "tether-sdk==${TETHER_VERSION}" \
++    && chmod 0755 /opt/harness/bin/run
++
++ENV PATH="/opt/harnessbench/frontend-bin:/usr/local/bin:/opt/tether/bin:${PATH}" \
++    NANOBOT_STREAM_IDLE_TIMEOUT_S=7200 \
++    NANOBOT_OPENAI_COMPAT_TIMEOUT_S=7200 \
++    NANOBOT_LLM_TIMEOUT_S=0
++
++# BEGIN NANOBOT LOGIN-SHELL PATH
++RUN printf '%s\n' \
++    'export PATH="/usr/local/bin:/opt/tether/bin:$PATH"' \
++    > /etc/profile.d/harnessbench-path.sh \
++    && chmod 0644 /etc/profile.d/harnessbench-path.sh
++# END NANOBOT LOGIN-SHELL PATH
++
++USER 1000:1000
++ENTRYPOINT ["/opt/harness/bin/run"]
+diff --git a/docker/harnesses/tether/entrypoint.sh b/docker/harnesses/tether/entrypoint.sh
+new file mode 100644
+index 0000000..105cee6
+--- /dev/null
++++ b/docker/harnesses/tether/entrypoint.sh
+@@ -0,0 +1,38 @@
++#!/usr/bin/env bash
++set -euo pipefail
++
++: "${HARNESSBENCH_PROMPT:?}"
++: "${HARNESSBENCH_CONFIG:?}"
++: "${HARNESSBENCH_WORKSPACE:?}"
++: "${HARNESSBENCH_STATE:?}"
++: "${HARNESSBENCH_TRACE:?}"
++
++export HOME="${HARNESSBENCH_STATE}/home"
++mkdir -p "${HOME}" "${HARNESSBENCH_TRACE}"
++runtime_config="${HARNESSBENCH_STATE}/providers.yaml"
++cp "${HARNESSBENCH_CONFIG}" "${runtime_config}"
++# The render step writes `# model: <id>` and `# turns: <n>` on the first lines.
++model="$(sed -n 's/^# model: //p' "${runtime_config}" | head -1)"
++turns="$(sed -n 's/^# turns: //p' "${runtime_config}" | head -1)"
++prompt="$(<"${HARNESSBENCH_PROMPT}")"
++
++export TETHER_PROVIDERS="${runtime_config}"
++export VLLM_API_KEY="${VLLM_API_KEY:-local-vllm-no-auth}"   # placeholder; the trial proxy injects the real key
++export TETHER_DB="${HARNESSBENCH_STATE}/tether.db"   # state stays outside the graded workspace
++export TETHER_ENV_PASSTHROUGH="PATH,NODE_PATH,GIT_CONFIG_GLOBAL"
++
++set +e
++cd "${HARNESSBENCH_WORKSPACE}"
++tether run \
++  --model "harnessbench/${model}" \
++  --tools bash,edit \
++  --max-steps "${turns:-150}" \
++  "${prompt}" \
++  > >(tee "${HARNESSBENCH_TRACE}/events.log") \
++  2> >(tee "${HARNESSBENCH_TRACE}/stderr.log" >&2)
++status=$?
++set -e
++
++[[ -f "${TETHER_DB}" ]] && cp "${TETHER_DB}" "${HARNESSBENCH_TRACE}/tether.db"
++chmod -R a+rX "${HARNESSBENCH_WORKSPACE}" "${HARNESSBENCH_TRACE}" 2>/dev/null || true
++exit "${status}"
+diff --git a/tools/harness_runtime.py b/tools/harness_runtime.py
+index c57ba22..e8763dc 100644
+--- a/tools/harness_runtime.py
++++ b/tools/harness_runtime.py
+@@ -67,6 +67,14 @@ SPECS = {
+         config_name="config.json",
+         docker_context=HARNESS_DOCKER_DIR / "nanobot",
+     ),
++    "tether": HarnessSpec(
++        harness_id="tether",
++        version="0.2.5",
++        image="harnessbench/tether:0.2.5",
++        protocol="chat_completions",
++        config_name="providers.yaml",
++        docker_context=HARNESS_DOCKER_DIR / "tether",
++    ),
+     "goose": HarnessSpec(
+         harness_id="goose",
+         version="1.44.0",
+@@ -291,6 +299,19 @@ def render_harness_config(
+         }
+         return json.dumps(config, ensure_ascii=False, indent=2) + "\n"
+ 
++    if spec.harness_id == "tether":
++        entry = {
++            "kind": "openai",
++            "base_url": base_url,
++            "api_key_env": "VLLM_API_KEY",
++            "context_tokens": context_window,
++            "fold_after": 8,
++            "timeout": 1800,
++            "params": {"temperature": temperature, "max_tokens": max_tokens},
++        }
++        header = f"# model: {model}\n# turns: {max_agent_turns}\n"
++        return header + yaml.safe_dump({"harnessbench": entry}, sort_keys=False)
++
+     if spec.harness_id == "goose":
+         config = {
+             "provider": "openai",

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/bench/run.py

@@ -20,6 +20,7 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 TASK_CFG = {  # tether tools / step cap / wall timeout
     "code-simple": ("edit,bash", 30, 600), "code-medium": ("edit,bash", 40, 900), "code-hard": ("edit,bash", 50, 1200),
     "focus": ("edit,bash,mem", 30, 600),
+    "plan": ("edit,bash", 20, 420), "codereview": ("edit,bash", 20, 420),
     "qa": ("", 10, 300), "content": ("", 10, 300), "review": ("edit", 15, 420),
 }
 

tether_sdk-0.2.6/bench/tasks/codereview/goal.txt

@@ -0,0 +1 @@
+Do not edit any file. Review inventory.py. Call done with a numbered list of the real defects you find: for each, name the function, say what is wrong and give the one-line fix. Report only real bugs, no style remarks.

tether_sdk-0.2.6/bench/tasks/codereview/ws/inventory.py

@@ -0,0 +1,40 @@
+"""Inventory helpers for a small shop."""
+import sqlite3
+
+
+def page(items, number, size=10):
+    """Return page `number` (1-based) of `items`."""
+    start = number * size
+    return items[start:start + size]
+
+
+def add_tag(item, tag, tags=[]):
+    tags.append(tag)
+    item["tags"] = tags
+    return item
+
+
+def total_price(lines):
+    total = 0.0
+    for line in lines:
+        total += line["price"] * line["qty"]
+    return total
+
+
+def is_free(price):
+    return price == 0.0
+
+
+def find_by_name(conn, name):
+    cur = conn.execute("SELECT id, name FROM items WHERE name = '" + name + "'")
+    return cur.fetchall()
+
+
+def load_stock(path):
+    f = open(path)
+    data = f.read()
+    return dict(line.split(",") for line in data.splitlines())
+
+
+def stock_of(stock, name):
+    return int(stock[name])

tether_sdk-0.2.6/bench/tasks/plan/goal.txt

@@ -0,0 +1 @@
+Do not edit any file. Read svc/client.py and svc/config.py, then call done with an implementation plan (a numbered list of 6 to 10 steps) for adding client-side retries with exponential backoff and jitter to the HTTP client. The plan must name the exact files and functions to change, say how the retry limit and base delay become settings, say which failures are retried (for example HTTP 429 and 5xx, timeouts) and which are not, say how Retry-After is honoured, and say how it will be tested without a real network. Plan only, no code.

tether_sdk-0.2.6/bench/tasks/plan/ws/README.md

@@ -0,0 +1,3 @@
+# svc
+
+Tiny service layer. All network calls go through `svc/client.py` (`get`, `post`). Settings live in `svc/config.py`. Tests live in `tests/` (none for the client yet).

tether_sdk-0.2.6/bench/tasks/plan/ws/svc/client.py

@@ -0,0 +1,18 @@
+"""HTTP client used by every service call."""
+import json
+import urllib.request
+
+from svc.config import BASE_URL, TIMEOUT
+
+
+def get(path):
+    with urllib.request.urlopen(BASE_URL + path, timeout=TIMEOUT) as resp:
+        return json.loads(resp.read())
+
+
+def post(path, payload):
+    req = urllib.request.Request(
+        BASE_URL + path, data=json.dumps(payload).encode(), headers={"Content-Type": "application/json"}
+    )
+    with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+        return json.loads(resp.read())

tether_sdk-0.2.6/bench/tasks/plan/ws/svc/config.py

@@ -0,0 +1,3 @@
+"""Settings."""
+BASE_URL = "https://api.example.internal"
+TIMEOUT = 5

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/docs/release-notes.md

@@ -1,5 +1,16 @@
 # Release Notes
 
+## v0.2.6 (2026-10-23)
+
+Found by using tether as its own SWE agent and by the v0.2.5 post-release check: a sandbox that refused harmless commands, sessions that only read, and a `query` that could not say why it found nothing. Closes #77, #93, #125, #127.
+
+### Fixes
+
+- CLI: `tether query` now says why nothing matched (#93): `Error: unknown session` with exit code 1 for a wrong id, `No chunks are indexed for <id> yet` for an empty session, and the number of indexed chunks otherwise. `search_chunks` also tries a prefix match (`loop*`) after the AND and OR matches, so `loop` finds `looping`.
+- Store: `SQLiteStore(":memory:")` no longer creates a file literally named `:memory:` in the working directory (#77). The path now maps to a temporary file outside the workspace, so every store method still shares one database.
+- Sandbox: with `bwrap` active, `bash` no longer refuses commands by text for `..`, absolute paths outside the workspace, or `.env`/`.tether`/`.git/config` mentions (#125). The kernel mounts already enforce them (read-only root, hidden `$HOME`, masked secrets), so the text rules only produced false refusals such as `ls ~/..` or `cat /etc/hosts`. They remain the fallback when `bwrap` is missing, and `sudo`, `su`, disk tools, `rm -rf /`, `chmod 777`, fork bombs and `~/.ssh` stay refused in both modes.
+- Sandbox: `.env.example`, `.env.sample`, `.env.template` and `.env.dist` are readable and writable; real `.env`, `.env.local`, `.env.production` stay masked and protected. Templates hold no secrets.
+
 ## v0.2.5 (2026-10-23)
 
 Found by benchmarking the same models inside Tether and inside a plain tool loop (7 tasks, 10+ models): model idioms made the single-`act` grammar fail invisibly, and loops or oversized prompts burned steps and tokens. Closes #76, #81, #86, #89, #92 and the shell-idiom bugs #109, #110.
@@ -46,6 +57,8 @@ Dogfooding fixes: the four milestone bugs (#74 #75 #85 #88) plus the friction fo
 
 ### Fixes
 
+- Harness: a session that only reads gets a deterministic hint (#127). After 12 consecutive read-only steps with no change at all, then every 8 more, the observation ends with `[NUDGE] No file changes in N steps. Make your edit now, or call `done` with what you found.` (0 static prompt tokens). Before, the quiet nudge started only after a first change, so a model that never edited (nemotron-3-ultra and glm-5.3 on scoped briefs: 40 steps, 150k to 215k prompt tokens, no change) was never told.
+- Harness: `awk`/`gawk`/`mawk` count as read-only (unless they print to a file, pipe to a shell, call `system()` or edit in place) and as range-shift reads of one file, so the #92 stall guard sees `awk 'NR>=a && NR<=b' f` loops. `NR>=5` used to look like a redirect, also inside compound commands (`grep ...; awk 'NR>=5' f`), which silently turned the nudges off.
 - Store: a `RUNNING` session whose worker pid no longer exists is flipped to `FAILED` (`Worker died (pid N) before finishing`) when read via `get_session`/`list_sessions`, so `status`, `list`, `wait` and `read` no longer report a killed worker as running forever (#85). A pid owned by another user counts as alive.
 - Providers: `429` retries wait `Retry-After` (else 10s doubling, capped 30s) and get up to 5 attempts instead of 3 quick ones, so rate-limited hosted models (NVIDIA free tier) no longer fail the session after 3 quick attempts.
 - Providers: each `post_with_retry` attempt is now bounded by a total `asyncio.wait_for(timeout)` deadline, so a trickling/stalled response cannot hang past the configured timeout; the deadline is retried like other transient errors and shows as `TimeoutError` (vs `ReadTimeout`) in the final `ProviderError` (#88).

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/docs/testing.md

@@ -85,7 +85,7 @@ trigger it, script the reply; if infrastructure must fail, add a fault to the pr
 
 ## Model conformance bench (developers only)
 
-`bench/` holds seven tasks (the `focus` task checks that an exact single-file goal is not lost in a distractor-heavy repo) with hidden-test graders and three runners (Tether, a plain tool loop,
+`bench/` holds nine tasks (the `focus` task checks that an exact single-file goal is not lost in a distractor-heavy repo) with hidden-test graders and three runners (Tether, a plain tool loop,
 Claude Code) so the same model can be compared across harnesses and releases. It needs real
 models, so it is not in CI and not in the package: use it when onboarding a model or before a
 release to see friction that scripted tests cannot (the shell-wrapper, bare-command and

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/docs/tutorial/security-and-sandbox.md

@@ -13,7 +13,7 @@ Tether never relies on system prompt instructions ("please do not read `.env` or
 ## Four Layers of Deterministic Defense
 
 ### 1. Canonical Path Confinement (`resolve_safe_path`)
-Every path passed to `edit` or referenced in `bash` is canonicalized via `Path.resolve()` and verified to reside inside `workspace_root`. Traversal attempts (`../../etc/passwd`) raise `SandboxViolationError` before touching the filesystem.
+Every path passed to `edit` or referenced in `bash` is canonicalized via `Path.resolve()` and verified to reside inside `workspace_root`. Traversal attempts (`../../etc/passwd`) raise `SandboxViolationError` before touching the filesystem. For `bash`, the kernel jail (below) is the boundary when `bwrap` is available: path and `.env` text checks on the command line run only in the no-`bwrap` fallback, so harmless commands such as `ls ~/..` are not refused for how they look. The cheap red lines (`sudo`, `su`, disk tools, `rm -rf /`, `chmod 777`, fork bombs, `~/.ssh`) are checked in both modes. `.env.example`, `.env.sample`, `.env.template` and `.env.dist` are not treated as secrets.
 
 ### 2. Protected Sensitive Paths
 Even within `workspace_root`, Tether deterministically blocks access to sensitive files and directories:

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/e2e/test_limits.py

@@ -66,3 +66,20 @@ def test_budget_holds_with_a_wide_fold_window(tether: Tether, chaos) -> None:
     assert d["rc"] == 0
     for req in chaos.requests:
         assert _size(req) <= 1500 * 1.3, f"prompt grew past the budget: ~{_size(req)} tokens"
+
+
+def test_awk_ranges_of_one_file_count_as_range_shift_reads(tether: Tether, chaos) -> None:
+    (tether.ws / "big.py").write_text("x = 1\n" * 300)
+    reads = [f"bash awk 'NR>={i * 20 + 1} && NR<={i * 20 + 20}' big.py" for i in range(12)]
+    chaos.script(*reads)
+    d = tether.run("explore one file", "--tools", "bash", "--max-steps", "30")
+    assert any("reads of `big.py`" in o for o in tether.tool_outputs(d["id"]))
+
+
+def test_explore_nudge_after_twelve_reads_without_a_change(tether: Tether, chaos) -> None:
+    for i in range(14):
+        (tether.ws / f"f{i}.txt").write_text(f"file {i}\n")
+    chaos.script(*[f"bash cat f{i}.txt" for i in range(14)], ("done", "ok"))
+    d = tether.run("read everything", "--tools", "bash", "--max-steps", "30")
+    outs = tether.tool_outputs(d["id"])
+    assert sum("[NUDGE] No file changes in 12 steps" in o for o in outs) == 1, outs[-3:]

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/e2e/test_sandbox.py

@@ -3,6 +3,10 @@ result never depends on the model's obedience; tether alone must say no."""
 
 from __future__ import annotations
 
+import shutil
+
+import pytest
+
 from e2e.conftest import Tether
 
 
@@ -60,3 +64,14 @@ def test_verify_gate_can_run_a_tool_installed_under_home(tether: Tether, chaos)
     chaos.script(("done", "ok"))
     d = tether.run("x", "--verify", "gatetool", "--tools", "bash")
     assert d["rc"] == 0, d
+
+
+@pytest.mark.skipif(shutil.which("bwrap") is None, reason="needs bwrap")
+def test_bash_reads_env_template_but_not_the_secret(tether: Tether, chaos) -> None:
+    (tether.ws / ".env").write_text("TOKEN=hunter2")
+    (tether.ws / ".env.example").write_text("TOKEN=\n")
+    chaos.script("bash cat .env.example", "bash cat .env", ("done", "ok"))
+    r = tether.run("read env files", "--tools", "bash")
+    template, secret = tether.tool_outputs(r["id"])[:2]
+    assert "TOKEN=" in template and "Sandbox violation" not in template, template
+    assert "hunter2" not in secret, secret  # masked by the kernel mount, not by a text rule

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/tests/test_cli.py

@@ -156,3 +156,19 @@ async def test_stop_terminates_a_running_worker(
     assert await _async_main(["stop", rec.id, "--json", "--db", db_arg]) == 0
     assert '"kind": "stopped"' in capsys.readouterr().out
     assert len(killed) == 1  # a finished session is left alone
+
+
+async def test_query_reports_why_nothing_matched(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    db_arg = str(tmp_path / "tether.db")
+    store = SQLiteStore(db_path=db_arg)
+    rec = store.create_session("g")
+    assert await _async_main(["query", "ses_nope", "x", "--db", db_arg]) == 1
+    assert "unknown session `ses_nope`" in capsys.readouterr().err
+    assert await _async_main(["query", rec.id, "anything", "--db", db_arg]) == 0
+    assert "No chunks are indexed for" in capsys.readouterr().out
+    store.add_observation(rec.id, step=1, cmd="bash x", raw_output="alpha beta gamma")
+    assert await _async_main(["query", rec.id, "nonexistent_xyz", "--db", db_arg]) == 0
+    out = capsys.readouterr().out
+    assert "1 chunks indexed" in out and "nonexistent_xyz" in out

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/tests/test_harness.py

@@ -11,7 +11,7 @@ import pytest
 from tests.conftest import FakeScriptedProvider
 from tether import ActionCall, Harness, ModelResponse, register_provider, tool
 from tether.decorator import ToolSpec
-from tether.harness import detect_cycle, read_target, spawn_detached_worker
+from tether.harness import detect_cycle, is_quiet, read_target, spawn_detached_worker
 from tether.store import SQLiteStore
 
 
@@ -662,3 +662,59 @@ async def test_context_overflow_warns_once_on_stderr(
     err = capsys.readouterr().err
     assert err.count("over --context-tokens 20") == 1
     assert "raise the budget" in err
+
+
+async def test_explore_nudge_when_nothing_changes(tmp_path: Path) -> None:
+    run = await _run_commands(tmp_path, [f"bash cat f{i}" for i in range(14)])  # no change at all
+    obs = run.provider.store.list_observations(run.session.id)
+    steps = [o.step for o in obs.values() if "[NUDGE] No file changes in 12 steps" in o.raw_output]
+    assert steps == [12]
+
+
+async def test_explore_nudge_repeats_while_the_model_only_reads(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("tether.harness.EXPLORE_NUDGE_STEPS", 2)
+    monkeypatch.setattr("tether.harness.EXPLORE_NUDGE_EVERY", 3)
+    run = await _run_commands(tmp_path, [f"bash cat f{i}" for i in range(9)])
+    obs = run.provider.store.list_observations(run.session.id)
+    assert [o.step for o in obs.values() if "[NUDGE] No file changes" in o.raw_output] == [2, 5, 8]
+
+
+async def test_explore_nudge_is_off_after_a_change(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("tether.harness.EXPLORE_NUDGE_STEPS", 2)
+    run = await _run_commands(tmp_path, ["ping a.com", "bash cat f0", "bash cat f1", "bash cat f2"])
+    obs = run.provider.store.list_observations(run.session.id)
+    assert not [o for o in obs.values() if "[NUDGE] No file changes in" in o.raw_output]
+
+
+@pytest.mark.parametrize(
+    ("cmd", "quiet"),
+    [
+        ("awk 'NR>=470 && NR<=500 {printf \"%d:%s\\n\", NR, $0}' tether/cli.py", True),
+        ("bash awk '/a/{n++} END{print n}' README.md", True),
+        ("awk '{print $1 > \"out.txt\"}' f", False),
+        ("awk 'BEGIN{system(\"rm x\")}'", False),
+        ("awk '{print}' f | tee g", False),
+        ("gawk -i inplace '{print}' f", False),
+    ],
+)
+def test_awk_is_quiet_unless_it_writes(cmd: str, quiet: bool) -> None:
+    assert is_quiet(cmd) is quiet
+    assert (read_target(cmd) is not None) is quiet
+
+
+@pytest.mark.parametrize(
+    ("cmd", "quiet"),
+    [
+        ("grep -n x f; awk 'NR>=820 && NR<=856' f", True),  # `>=` is a comparison, not a redirect
+        ("cat f | awk 'NR>5'", True),
+        ("echo hi > out.txt", False),
+        ("cat a >> b", False),
+        ("ls >out", False),
+    ],
+)
+def test_comparison_operators_are_not_redirects(cmd: str, quiet: bool) -> None:
+    assert is_quiet(cmd) is quiet

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/tests/test_security_hardening.py

@@ -100,7 +100,7 @@ async def test_web_fetch_blocks_private_addresses(
     ],
 )
 def test_program_args_are_not_paths(cmd: str, tmp_path: Path) -> None:
-    SandboxPolicy(workspace_root=tmp_path).validate_bash_command(cmd)
+    SandboxPolicy(workspace_root=tmp_path, use_kernel_sandbox=False).validate_bash_command(cmd)
 
 
 @pytest.mark.parametrize(
@@ -108,10 +108,61 @@ def test_program_args_are_not_paths(cmd: str, tmp_path: Path) -> None:
     ["sed -n p /etc/hosts", "awk -f /etc/passwd x", "cat /etc/hosts", "cd . && cat /etc/hosts"],
 )
 def test_real_absolute_paths_still_blocked(cmd: str, tmp_path: Path) -> None:
+    with pytest.raises(SandboxViolationError):  # text rules are the no-bwrap fallback
+        SandboxPolicy(workspace_root=tmp_path, use_kernel_sandbox=False).validate_bash_command(cmd)
+
+
+@pytest.mark.parametrize(
+    "cmd",
+    ["ls ~/..", "cat /etc/hosts", "cat .tether/x", "cat .git/config"],
+)
+def test_kernel_sandbox_leaves_path_policing_to_the_mounts(
+    cmd: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(sb_mod, "_can_use_bwrap", lambda: True)
+    SandboxPolicy(workspace_root=tmp_path).validate_bash_command(cmd)  # no false refusal
+    monkeypatch.setattr(sb_mod, "_can_use_bwrap", lambda: False)
+    with pytest.raises(SandboxViolationError):  # same commands stay refused without bwrap
+        SandboxPolicy(workspace_root=tmp_path).validate_bash_command(cmd)
+
+
+@pytest.mark.parametrize("cmd", ["sudo ls", "rm -rf /", "cat ~/.ssh/id_rsa", "chmod 777 x"])
+def test_kernel_sandbox_keeps_the_cheap_red_lines(
+    cmd: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(sb_mod, "_can_use_bwrap", lambda: True)
     with pytest.raises(SandboxViolationError):
         SandboxPolicy(workspace_root=tmp_path).validate_bash_command(cmd)
 
 
+@pytest.mark.parametrize(
+    ("name", "secret"),
+    [(".env", True), (".env.local", True), (".env.example", False), (".env.dist", False)],
+)
+def test_env_templates_are_readable_secrets_are_not(
+    name: str, secret: bool, tmp_path: Path
+) -> None:
+    (tmp_path / name).write_text("K=v")
+    sp = SandboxPolicy(workspace_root=tmp_path, use_kernel_sandbox=False)
+    if secret:
+        with pytest.raises(SandboxViolationError):
+            sp.resolve_safe_path(name)
+        with pytest.raises(SandboxViolationError):
+            sp.validate_bash_command(f"cat {name}")
+    else:
+        assert sp.resolve_safe_path(name).name == name
+        sp.validate_bash_command(f"cat {name}")
+
+
+@needs_bwrap
+async def test_masked_secret_and_env_example_under_real_bwrap(tmp_path: Path) -> None:
+    (tmp_path / ".env").write_text("TOKEN=secret")
+    (tmp_path / ".env.example").write_text("TOKEN=\n")
+    sp = SandboxPolicy(workspace_root=tmp_path)
+    code, out = await sp.execute_bash_with_code("cat .env.example; echo ---; cat .env")
+    assert "TOKEN=" in out.split("---")[0] and "secret" not in out, out
+
+
 def test_unknown_tool_name_rejected(tmp_path: Path) -> None:
     with pytest.raises(ValueError, match="bahs"):
         Harness(tools="bash,bahs", db_path=tmp_path / "t.db")

{tether_sdk-0.2.5 → tether_sdk-0.2.6}/tests/test_store.py

@@ -314,3 +314,26 @@ def test_reap_dead_keeps_other_users_pid(tmp_path: Path, monkeypatch: pytest.Mon
     monkeypatch.setattr("os.kill", deny)
     got = store.get_session(rec.id)
     assert got is not None and got.status == "RUNNING"
+
+
+def test_count_chunks_and_prefix_fallback(tmp_path: Path) -> None:
+    store = SQLiteStore(db_path=tmp_path / "t.db")
+    rec = store.create_session("g")
+    assert store.count_chunks([]) == 0
+    assert store.count_chunks([rec.id]) == 0
+    store.add_observation(rec.id, step=1, cmd="bash x", raw_output="the model keeps looping here")
+    assert store.count_chunks([rec.id]) >= 1
+    hits = store.search_chunks("loop", session_ids=[rec.id])  # prefix: loop -> looping
+    assert hits and "looping" in hits[0].content
+    assert store.search_chunks("zz", session_ids=[rec.id]) == []  # too short for a prefix match
+
+
+def test_memory_path_does_not_create_a_file_in_cwd(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    store = SQLiteStore(":memory:")
+    rec = store.create_session("g")
+    assert store.get_session(rec.id) is not None
+    assert not (tmp_path / ":memory:").exists()
+    assert store.db_path.parent != tmp_path