@ponythewhite/base-context 1.0.15 → 1.0.16

package/dist/skills/agent-message/SKILL.md

@@ -62,7 +62,8 @@ if child is not None:
 
 ## Result capsules
 
-Use `send()` for short coordination. Use `send_result()` for a full public report:
+Use `send()` for short steering, blockers, and decisions. Use `send_result()`
+for substantial findings or a final public report, not for a short message:
 
 ```python
 from pathlib import Path
@@ -74,7 +75,9 @@ receipt = await agent_message.send_result(
 )
 ```
 
-State conclusions, caveats, and decisions in the capsule. If it revises or
+State the outcome, important caveats, decisions, and evidence references in the
+capsule. Child findings are evidence, not independently verified truth. Retrieve
+details only when needed. If it revises or
 replaces earlier reports, name their exact report refs in the summary. With
 several updates, skim the capsules first, then retrieve the last relevant
 report or reports. Older reports remain readable. Do not treat unrelated
@@ -83,6 +86,9 @@ arrived. There is no automatic latest-wins, dropping, or coalescing.
 
 ## Safety
 
+- Avoid routine acknowledgements and repeated status broadcasts. Messaging an
+  idle child can start another turn; not every message needs a reply.
+
 - Do not delete a child immediately after `send`: delivered follow-ups may still
   be running and queued receipts have not run yet. Wait until observation shows
   the child is idle and its context is no longer needed before calling

package/dist/skills/bounded-inspect/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: bounded-inspect
+description: Inspect selected text windows and JSON fields from project files under shared source and serialized-output byte budgets. Emit one source-linked bundle; continue within oversized lines without repeating full reads.
+---
+
+# Bounded Inspect
+
+Use for repeated, selective file inspection. Keep tiny one-off reads inline.
+Historical conversation evidence belongs to `prime_context`, not this skill.
+Filesystem paths and byte cursors are **not native recovery refs**.
+
+```python
+bounded_inspect.emit(
+    bounded_inspect.text("runs/example/train.log", tail_lines=25),
+    bounded_inspect.json_fields("runs/example/metrics.json",
+        pointers=["/run", "/config", "/seed", "/eligible", "/failures",
+                  "/units", "/updates", "/skips", "/wall"]),
+    max_bytes=4096, max_source_bytes=65536,
+)
+```
+
+Selectors are lazy; only `emit` reads. It prints one JSON object and returns
+`None`, so a final cell expression does not duplicate the result. Stateless
+extraction works in ordinary, goal, and AUTONOMOUS sessions. It does not park,
+finish, or change autonomous limits. Consume the supplied evidence; do not
+rerun its generating command merely to get a smaller answer.
+
+## API and coverage
+
+- `text(path)` selects the first 25 lines. Choose one of `head_lines=N`,
+  `tail_lines=N`, `start_line=N, end_line=M`, or `cursor=item["next"]`.
+  Line ranges are 1-based and inclusive; omitted `end_line` means through EOF.
+- `json_fields(path, pointers=[...], max_source_bytes=65536)` uses exact JSON
+  pointers, including `~0` and `~1` escapes. An empty pointer selects the root.
+  Null stays null. Missing fields, invalid JSON, unavailable files, and oversized
+  values have distinct statuses. Selected values are never string-sliced. Numeric
+  tokens stay exact, including exponents and nested values; no float conversion.
+- `emit(*selectors, max_bytes=4096, max_source_bytes=65536)` shares both budgets
+  across all selectors, in order. `max_bytes` must be at least 128 for refusal
+  metadata. Raise explicit limits when necessary, not by an unbounded retry.
+
+`output_bytes` counts the complete UTF-8 JSON serialization, escaping, metadata,
+paths, warnings, and final newline. `source_bytes` counts bytes actually read,
+not file size or OS device traffic. The enclosing tool/protocol envelope is
+outside this budget; normal `ipython` retention still applies. `omitted` identifies
+unreturned selector indices in the original call; `omitted_fields` counts the
+unreturned suffix of requested pointers. Order important metadata first.
+
+Text includes a stat version, half-open byte range, starting line (or null),
+and next byte cursor. Partial Unicode lines advance at UTF-8 boundaries.
+A continuation advances, finishes, or explicitly refuses. Source-limited line
+seeking can return an empty window with an advancing cursor. Reuse the same
+path and returned cursor; modification or replacement returns `changed_source`.
+Stat tokens are practical guards, not immutable captures.
+
+Tail reads only a bounded suffix. If it cannot establish the requested start,
+`tail_prefix_unread` marks missing prefix coverage; terminal `tail_window_limit`
+means that coverage is incomplete. Absolute line numbers may be unknown. JSON parsing refuses files above the explicit source ceiling before
+reading. Large histories need a project-native summary producer, not larger
+unbounded `json.load` calls. Select scientific units, run/config/seed identifiers,
+eligibility, and failures together. Extraction does not infer quality crossings,
+repair failed controls, or turn unavailable measurements into zero.
+
+## Run where the data lives
+
+Use `python -m bounded_inspect`, or stage `src/bounded_inspect/__init__.py` once
+and execute that file with standard-library Python through existing authorized
+remote execution. Pass a JSON list on stdin:
+
+```json
+[{"kind":"text","path":"train.log","tail_lines":25},
+ {"kind":"json","path":"metrics.json","pointers":["/run","/units","/wall"]}]
+```
+
+CLI flags: `--max-bytes` and `--max-source-bytes`. No SSH setup is provided.
+Save a small parameterized project parser after demonstrated reuse. Log full
+execution evidence to explicit files when needed: this skill cannot recover
+bytes that Bash or another capture already discarded.

package/dist/skills/bounded-inspect/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "bounded-inspect"
+version = "0.1.0"
+description = "Bounded text and selected JSON file evidence"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+bounded-inspect = "bounded_inspect:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bounded_inspect"]

package/dist/skills/bounded-inspect/src/bounded_inspect/__init__.py

@@ -0,0 +1,313 @@
+"""Bounded file evidence. Select lazily; emit one shared-budget JSON bundle."""
+
+import argparse
+import json
+import os
+import stat
+import sys
+from dataclasses import dataclass
+
+__all__ = ["text", "json_fields", "emit"]
+
+
+@dataclass(frozen=True)
+class _Selection:
+    kind: str
+    path: str
+    options: dict
+
+
+def text(path, *, head_lines=None, tail_lines=None, start_line=None, end_line=None, cursor=None):
+    """Select UTF-8 lines (1-based, inclusive), or resume a returned byte cursor."""
+    modes = sum(value is not None for value in (head_lines, tail_lines, start_line, cursor))
+    if modes > 1 or (end_line is not None and start_line is None):
+        raise ValueError("choose head, tail, line range, or cursor")
+    for value in (head_lines, tail_lines, start_line, end_line):
+        if value is not None and (not isinstance(value, int) or value < 1):
+            raise ValueError("line counts must be positive integers")
+    if start_line is not None and end_line is not None and end_line < start_line:
+        raise ValueError("end_line precedes start_line")
+    if modes == 0:
+        head_lines = 25
+    return _Selection("text", os.fspath(path), dict(head=head_lines, tail=tail_lines,
+                      start=start_line, end=end_line, cursor=dict(cursor) if cursor else cursor))
+
+
+def json_fields(path, *, pointers, max_source_bytes=65536):
+    """Select exact RFC 6901 pointers; missing is distinct from JSON null."""
+    pointers = tuple(pointers)
+    if any(not isinstance(p, str) or (p and not p.startswith("/")) for p in pointers):
+        raise ValueError("pointers must be empty (root) or start with /")
+    if max_source_bytes < 0:
+        raise ValueError("max_source_bytes must be nonnegative")
+    return _Selection("json", os.fspath(path), dict(pointers=pointers, cap=max_source_bytes))
+
+
+def _version(info):
+    return [info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns]
+
+
+class _JsonNumber(str):
+    """A number token validated by json.loads, not converted through float/int."""
+
+
+def _serialized(value):
+    if isinstance(value, _JsonNumber):
+        return str(value)
+    if isinstance(value, dict):
+        return "{" + ",".join(_serialized(key) + ":" + _serialized(item) for key, item in value.items()) + "}"
+    if isinstance(value, list):
+        return "[" + ",".join(_serialized(item) for item in value) + "]"
+    return json.dumps(value, ensure_ascii=True, allow_nan=False, separators=(",", ":"))
+
+
+def _encoded(bundle):
+    # Count the complete wire envelope, including escaping and the final newline.
+    while True:
+        rendered = _serialized(bundle) + "\n"
+        size = len(rendered.encode("utf-8"))
+        if bundle["output_bytes"] == size:
+            return rendered
+        bundle["output_bytes"] = size
+
+
+def _read(handle, count, bundle):
+    data = handle.read(max(0, min(count, bundle["limits"]["source_bytes"] - bundle["source_bytes"])))
+    bundle["source_bytes"] += len(data)
+    return data
+
+
+def _cursor(path, version, offset, line, start, end, warnings):
+    return dict(path=path, version=version, offset=offset, line=line,
+                start_line=start, end_line=end, warnings=warnings)
+
+
+def _text(handle, selection, version, bundle):
+    options = selection.options
+    size = version[2]
+    cap = bundle["limits"]["source_bytes"] - bundle["source_bytes"]
+    cursor = options["cursor"]
+    warnings = []
+    offset, line = 0, 1
+    start, end = options["start"] or 1, options["end"] or options["head"]
+    if cursor is not None:
+        if cursor.get("path") != selection.path or cursor.get("version") != version:
+            return {"status": "changed_source", "next": None}, None
+        try:
+            offset, line = cursor["offset"], cursor["line"]
+            start, end = cursor["start_line"], cursor["end_line"]
+            warnings = cursor["warnings"]
+            if not isinstance(offset, int) or not 0 <= offset <= size:
+                raise ValueError()
+        except (KeyError, TypeError, ValueError):
+            return {"status": "invalid_cursor", "next": None}, None
+    elif options["tail"] is not None:
+        offset = max(0, size - cap)
+        line = 1 if offset == 0 else None
+        end = None
+    handle.seek(offset)
+    raw = _read(handle, size - offset, bundle)
+    if options["tail"] is not None:
+        # Work backwards only within the bounded suffix, never scan the prefix.
+        boundaries = [i + 1 for i, value in enumerate(raw) if value == 10 and i + 1 < len(raw)]
+        needed = options["tail"]
+        cut = boundaries[-needed] if len(boundaries) >= needed else 0
+        if offset and not cut:
+            warnings.append("tail_prefix_unread; absolute_line_unavailable")
+            while cut < len(raw) and raw[cut] & 0xC0 == 0x80:
+                cut += 1
+        if line is not None:
+            line += raw[:cut].count(b"\n")
+        offset += cut
+        raw = raw[cut:]
+    # Seek a requested line in bounded chunks. Cursors can advance without text.
+    if line is not None:
+        while line < start:
+            newline = raw.find(b"\n")
+            if newline < 0:
+                offset += len(raw)
+                raw = b""
+                break
+            offset += newline + 1
+            raw = raw[newline + 1:]
+            line += 1
+        if end is not None:
+            limit = end - line + 1
+            if limit <= 0:
+                raw = b""
+            else:
+                pos = 0
+                for _ in range(limit):
+                    newline = raw.find(b"\n", pos)
+                    if newline < 0:
+                        break
+                    pos = newline + 1
+                else:
+                    raw = raw[:pos]
+    try:
+        decoded = raw.decode("utf-8")
+    except UnicodeDecodeError as error:
+        if error.reason != "unexpected end of data" or offset + len(raw) == size:
+            return {"status": "invalid_utf8", "byte": offset + error.start, "next": None}, None
+        decoded = raw[:error.start].decode("utf-8")
+    context = (selection.path, version, offset, line, start, end, warnings)
+    if not decoded:
+        seeking = line is not None and line < start and offset < size
+        done = offset == size or (end is not None and line is not None and line > end)
+        status = "complete" if done else "seeking" if seeking and raw == b"" and cap else "source_limit"
+        next_cursor = _cursor(*context) if status == "seeking" else None
+        return dict(status=status, text="", range={"bytes": [offset, offset], "line": line},
+                    next=next_cursor, warnings=warnings), None
+    return {}, (decoded, context)
+
+
+def _text_prefix(decoded, context, length):
+    path, version, offset, line, start, end, warnings = context
+    value = decoded[:length]
+    stop = offset + len(value.encode("utf-8"))
+    next_line = None if line is None else line + value.count("\n")
+    done = stop == version[2] or (end is not None and next_line is not None and next_line > end)
+    status = ("tail_window_limit" if warnings else "complete") if done else "partial" if length else "output_limit"
+    following = None if done or not length else _cursor(path, version, stop, next_line, start, end, warnings)
+    return dict(status=status, text=value, range={"bytes": [offset, stop], "line": line},
+                next=following, warnings=warnings)
+
+
+def _constant(value):
+    raise ValueError("nonstandard JSON constant")
+
+
+def _json(handle, selection, version, bundle):
+    cap = min(selection.options["cap"], bundle["limits"]["source_bytes"] - bundle["source_bytes"])
+    if version[2] > cap:
+        return {"status": "source_limit", "size_bytes": version[2], "source_ceiling": cap}, None
+    raw = _read(handle, version[2], bundle)
+    try:
+        data = json.loads(raw, parse_float=_JsonNumber, parse_int=_JsonNumber, parse_constant=_constant)
+    except (ValueError, UnicodeError, RecursionError):
+        return {"status": "invalid_json"}, None
+    fields = []
+    for pointer in selection.options["pointers"]:
+        value = data
+        try:
+            for part in pointer.split("/")[1:] if pointer else []:
+                if any(part[i:i + 2] not in ("~0", "~1") for i, ch in enumerate(part) if ch == "~"):
+                    raise ValueError()
+                part = part.replace("~1", "/").replace("~0", "~")
+                if isinstance(value, list):
+                    if not part.isascii() or not part.isdigit() or (len(part) > 1 and part[0] == "0"):
+                        raise KeyError()
+                    value = value[int(part)]
+                elif isinstance(value, dict):
+                    value = value[part]
+                else:
+                    raise KeyError()
+            fields.append(dict(pointer=pointer, status="ok", value=value))
+        except (KeyError, IndexError):
+            fields.append(dict(pointer=pointer, status="missing"))
+        except ValueError:
+            fields.append(dict(pointer=pointer, status="invalid_pointer"))
+    return {"status": "complete", "fields": [], "omitted_fields": len(fields)}, fields
+
+
+def emit(*selections, max_bytes=4096, max_source_bytes=65536):
+    """Print one JSON bundle, within shared source/output byte limits. Return None."""
+    if not isinstance(max_bytes, int) or max_bytes < 128:
+        raise ValueError("max_bytes must be at least 128 (refusal envelope)")
+    if not isinstance(max_source_bytes, int) or max_source_bytes < 0:
+        raise ValueError("max_source_bytes must be nonnegative")
+    if any(not isinstance(selection, _Selection) for selection in selections):
+        raise TypeError("emit accepts text/json_fields selectors")
+    bundle = dict(items=[], omitted={"from": 0, "count": len(selections), "reason": "output_budget"},
+                  source_bytes=0, output_bytes=0,
+                  limits={"output_bytes": max_bytes, "source_bytes": max_source_bytes})
+    if len(_encoded(bundle).encode("utf-8")) > max_bytes:
+        bundle = dict(status="output_limit", omitted_count=len(selections), source_bytes=0, output_bytes=0)
+        print(_encoded(bundle), end="")
+        return None
+    for index, selection in enumerate(selections):
+        before = bundle["source_bytes"]
+        item = dict(index=index, path=selection.path, kind=selection.kind)
+        details = None
+        try:
+            # Unbuffered regular files: the counter is actual bytes read, not requested bytes.
+            with open(selection.path, "rb", buffering=0) as handle:
+                info = os.fstat(handle.fileno())
+                if not stat.S_ISREG(info.st_mode):
+                    result = {"status": "not_regular_file"}
+                else:
+                    version = _version(info)
+                    item["version"] = version
+                    if selection.kind == "text":
+                        result, details = _text(handle, selection, version, bundle)
+                    else:
+                        result, details = _json(handle, selection, version, bundle)
+                    if _version(os.fstat(handle.fileno())) != version or _version(os.stat(selection.path)) != version:
+                        result, details = {"status": "changed_source", "next": None}, None
+                item.update(result)
+        except OSError as error:
+            item.update(status="unavailable", error=error.__class__.__name__, errno=error.errno)
+        item["source_bytes"] = bundle["source_bytes"] - before
+        bundle["items"].append(item)
+        bundle["omitted"].update({"from": index + 1, "count": len(selections) - index - 1})
+
+        def fits():
+            return len(_encoded(bundle).encode("utf-8")) <= max_bytes
+
+        if details is not None and selection.kind == "text":
+            decoded, context = details
+            item.update(_text_prefix(decoded, context, len(decoded)))
+            if not fits():
+                low, high = 0, len(decoded)
+                while low < high:
+                    middle = (low + high + 1) // 2
+                    item.update(_text_prefix(decoded, context, middle))
+                    if fits():
+                        low = middle
+                    else:
+                        high = middle - 1
+                item.update(_text_prefix(decoded, context, low))
+        elif details is not None:
+            for field_index, field in enumerate(details):
+                item["fields"].append(field)
+                item["omitted_fields"] = len(details) - field_index - 1
+                if not fits():
+                    item["fields"][-1] = dict(pointer=field["pointer"], status="value_limit")
+                    item["status"] = "partial"
+                    if not fits():
+                        item["fields"].pop()
+                        item["omitted_fields"] += 1
+                        break
+        if not fits():
+            bundle["items"].pop()
+            bundle["omitted"].update({"from": index, "count": len(selections) - index})
+            break
+    # Budget refusal may follow real I/O, so keep those source bytes in the envelope.
+    rendered = _encoded(bundle)
+    if len(rendered.encode("utf-8")) > max_bytes:
+        bundle = dict(status="output_limit", omitted_count=len(selections),
+                      source_bytes=bundle["source_bytes"], output_bytes=0)
+        rendered = _encoded(bundle)
+    print(rendered, end="")
+    return None
+
+
+def main():
+    """Standalone: stage this file once, then pass a small JSON request on stdin."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--max-bytes", type=int, default=4096)
+    parser.add_argument("--max-source-bytes", type=int, default=65536)
+    args = parser.parse_args()
+    request = json.load(sys.stdin)
+    selections = []
+    for entry in request:
+        entry = dict(entry)
+        kind, path = entry.pop("kind"), entry.pop("path")
+        if kind not in ("text", "json"):
+            parser.error("kind must be text or json")
+        selections.append((text if kind == "text" else json_fields)(path, **entry))
+    emit(*selections, max_bytes=args.max_bytes, max_source_bytes=args.max_source_bytes)
+
+
+if __name__ == "__main__":
+    main()

package/dist/skills/bounded-inspect/src/bounded_inspect/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+main()

package/dist/skills/job-watch/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: job-watch
+description: Watch launched jobs with native completion callbacks or scheduled read-only probes. Park owned continuation, suppress unchanged status, and deliver prepared evidence for failures, completion, changes, or required reports.
+---
+
+# Job Watch
+
+Use for repeated checks or jobs that outlive a short tool call. Tiny commands do not need a watch. Launch once with `bash()` or an authorized project helper. This skill never launches a job, retries a run, starts the next stage, or completes a goal.
+
+```python
+job = bash(existing_authorized_command)
+w = await job_watch.watch(
+    job, job_id="run-1", completion_source="handle",
+    probe_command=existing_read_only_probe_command,
+    interval="5m", notify="terminal", report_every="5m", fields=["updates", "wall_seconds"],
+)
+await job_watch.park([w["id"]])
+```
+
+Continue useful independent work instead of parking when possible. `park` returns immediately. It holds only automatic goal/autonomous continuation until an event from a selected watch. The goal stays active. User messages and unrelated queued work still run. End the turn after parking; do not poll or sleep.
+
+## API
+
+- `await watch(job=None, *, job_id=None, completion_source, probe_command=None, interval="5m", notify="terminal", fields=None, report_every=None, deadline=None, probe_timeout=30)` registers once. Repeating the same active resource registration returns its existing watch. `fields` selects top-level progress keys for cached status, required reports, and `notify="changes"`. Include every metric needed in reports. Observation time never counts as a change. Intervals use existing schedule syntax, with a ten-second minimum. `deadline` is an ISO date; timeout is seconds.
+- `await status(id=None)` returns cached snapshots, not a new probe.
+- `await park(ids)` registers a wait without blocking the cell.
+- `await unregister(id)` stops observation. It is idempotent and never kills the monitored job. It may cancel an in-flight probe.
+
+Set `completion_source="probe"` for detached remote jobs. A successful SSH launcher exit is **not** remote completion. Probe-only registration requires `job_id`. A probe command must be an already authorized, noninteractive, read-only command in the project's native environment. Do not pass notebook closures. The command prints one JSON object of at most 16 KiB:
+
+```json
+{"observed_at":"2026-09-28T12:00:00Z","job_id":"run-1","state":"running","progress":{"updates":12,"wall_seconds":45},"attention":[],"evidence":["runs/run-1/metrics.json"]}
+```
+
+Use strings for exact identifiers and precision-sensitive values. Unsafe integers, nonfinite numbers, and precision-losing numeric tokens are rejected as unavailable observations.
+
+States are `running`, `succeeded`, `failed`, `cancelled`, and `unknown`. Preserve units, configuration/run identity, unavailable values, and comparison eligibility in selected fields. Put project-specific threshold or quality-gate warnings in `attention`. Missing/partial JSON or transport failure means unavailable evidence, not permission to restart training. New observability problems and terminal failures remain visible; repeated identical problems are suppressed.
+
+Checks do not require reports. Omit `report_every` unless the user requires periodic reports. Required reports include a prepared snapshot even when values did not change. Delayed observations show lateness; they do not pretend to have run on time. Notifications are about 2 KiB. Large fields are explicitly omitted and captured probe output remains in the supplied file locator. Bash may already have discarded output; use explicit project log files when complete execution evidence matters.
+
+Consume delivered evidence; inspect raw sources only for decisions. Compaction does not recreate a watch. Clean shutdown retains undelivered reports with their original IDs. If shutdown interrupts delivery and its acknowledgement, recovery reports delivery as unknown; it does not claim exactly-once crash recovery. After restart, only an authoritative probe can reconcile a job; a lost handle becomes unknown. Never attach by PID or relaunch automatically. Imported/forked declarations do not acquire ownership. Preserve resource exclusivity, authorized run counts, and stop conditions. Unregister at the requested endpoint.
+
+Pending watch state is limited to 64 KiB (less under smaller source limits). If undelivered evidence fills it, prior reports remain; monitoring stops with unknown, a reason, and a retained locator. This is not successful cadence preservation. The job keeps running. Resume delivery, unregister exhausted watches, and explicitly register again. No automatic retry.

package/dist/skills/job-watch/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "job-watch"
+version = "0.1.0"
+description = "Base Context owned job monitoring over the kernel host bridge"
+requires-python = ">=3.10"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/job_watch"]

package/dist/skills/job-watch/src/job_watch/__init__.py

@@ -0,0 +1,61 @@
+"""Monitor authorized jobs without model polling. Launch with bash(), not this skill."""
+from __future__ import annotations
+from typing import Any, Literal
+from rlm import host_request
+from rlm.bash import BashHandle
+try:
+    from rlm import job_watch as _runtime
+except ImportError:
+    _runtime = None
+
+
+async def watch(
+    job: BashHandle | None = None, *, job_id: str | None = None,
+    completion_source: Literal["handle", "probe"], probe_command: str | None = None,
+    interval: str = "5m", notify: Literal["terminal", "changes"] = "terminal",
+    fields: list[str] | None = None, report_every: str | None = None,
+    deadline: str | None = None, probe_timeout: float = 30,
+) -> dict[str, Any]:
+    """Register once. Probe commands must be authorized, noninteractive, and read-only.
+
+    A probe prints JSON: observed_at, job_id, state, progress, attention, evidence.
+    fields selects top-level progress keys; timestamps never trigger progress changes.
+    completion_source='probe' is required for detached remote jobs, including SSH launchers.
+    """
+    if _runtime is None:
+        raise RuntimeError("job-watch requires a runtime with job_watch_probe_v1; no watch was registered")
+    if completion_source not in {"handle", "probe"}:
+        raise ValueError("completion_source must be handle or probe")
+    if job is None and (completion_source == "handle" or not job_id):
+        raise ValueError("handle completion requires a BashHandle; probe-only watches require job_id")
+    resource = _runtime.identity(job) if job is not None else f"probe:{job_id}"
+    result = await host_request("job_watch.watch", {
+        "job_id": job_id or resource, "resource_id": resource,
+        "completion_source": completion_source, "probe_command": probe_command,
+        "interval": interval, "notify": notify, "fields": fields or [],
+        "report_every": report_every, "deadline": deadline, "timeout_ms": probe_timeout * 1000,
+    })
+    if job is not None and completion_source == "handle":
+        _runtime.bind(job, result["id"], result["generation"], job_id or resource)
+    return result
+
+
+async def status(id: str | None = None) -> dict[str, Any]:
+    """Return cached state only; never launch a probe or a model turn."""
+    return await host_request("job_watch.status", {} if id is None else {"id": id})
+
+
+async def park(ids: list[str]) -> dict[str, Any]:
+    """Declare no further owned continuation until a selected event. Returns immediately.
+
+    User messages and unrelated queued work still run. This does not pause the goal.
+    """
+    return await host_request("job_watch.park", {"ids": ids})
+
+
+async def unregister(id: str) -> dict[str, Any]:
+    """Stop watching, not the job. Repeated calls are harmless."""
+    result = await host_request("job_watch.unregister", {"id": id})
+    if _runtime is not None:
+        _runtime.unbind(id)
+    return result

package/dist/skills/rlm-heartbeat/SKILL.md

@@ -12,8 +12,8 @@ replace, pause, resume, or clear that user-level heartbeat.
 Call directly from the Python REPL:
 
 ```python
-await rlm_heartbeat.create("check test progress", interval="5m", label="tests")
-await rlm_heartbeat.create("watch build", delivery_mode="follow_up")
+await rlm_heartbeat.create("review current priorities", interval="30m", label="review")
+await rlm_heartbeat.create("review pending decisions", delivery_mode="follow_up")
 await rlm_heartbeat.list()
 await rlm_heartbeat.update("job-id", status="pause")
 await rlm_heartbeat.delete("job-id")
@@ -46,9 +46,13 @@ the session when it is busy:
 
 - Use this when the user asks you to start, create, schedule, or manage your own
   heartbeat without explicitly referring to `/heartbeat`.
-- Use this only for agent-internal recurring checks and long-running task
-  coordination.
+- Use this for recurring work that needs a model decision. For deterministic
+  job checks, prefer `job-watch` when available: it probes before deciding whether
+  to wake the model. Preserve every required report and any explicit heartbeat
+  request; do not silently replace the user's schedule.
 - Do not use this skill to satisfy a user's request to configure `/heartbeat`;
   that is a separate user-level surface.
-- Keep heartbeat instructions specific and actionable so each recurring turn
-  knows exactly what to inspect or continue.
+- Name the current authoritative state and an existing parameterized project
+  helper in monitoring instructions. Do not copy the same detailed status into
+  heartbeats, messages, notebook variables, and status documents. Reuse the
+  helper with current inputs; repetition never authorizes new jobs.

package/dist/utils/file-lines.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-lines.d.ts","sourceRoot":"","sources":["../../src/utils/file-lines.ts"],"names":[],"mappings":"AAEA,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAY,EACpB,eAAe,UAAQ,GACrB,MAAM,GAAG,SAAS,CAsBpB;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAY,EAAE,YAAY,UAAQ,GAAG,MAAM,GAAG,SAAS,CAKlH;AAED,wBAAuB,kBAAkB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvF,cAAc,CAAC,MAAM,CAAC,CA8BxB","sourcesContent":["import { closeSync, createReadStream, openSync, readSync } from \"node:fs\";\n\nexport function readFirstLineBufferSync(\n\tfilePath: string,\n\tmaxBytes = 64 * 1024,\n\tallowIncomplete = false,\n): Buffer | undefined {\n\tconst fd = openSync(filePath, \"r\");\n\tconst chunks: Buffer[] = [];\n\tlet position = 0;\n\ttry {\n\t\tconst buffer = Buffer.alloc(1024);\n\t\twhile (position < maxBytes) {\n\t\t\tconst count = readSync(fd, buffer, 0, Math.min(buffer.length, maxBytes - position), position);\n\t\t\tif (count === 0) break;\n\t\t\tconst chunk = buffer.subarray(0, count);\n\t\t\tconst newline = chunk.indexOf(0x0a);\n\t\t\tif (newline !== -1) {\n\t\t\t\tchunks.push(Buffer.from(chunk.subarray(0, newline + 1)));\n\t\t\t\treturn Buffer.concat(chunks);\n\t\t\t}\n\t\t\tchunks.push(Buffer.from(chunk));\n\t\t\tposition += count;\n\t\t}\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\treturn allowIncomplete && chunks.length > 0 ? Buffer.concat(chunks) : undefined;\n}\n\nexport function readFirstLineSync(filePath: string, maxBytes = 64 * 1024, completeOnly = false): string | undefined {\n\treturn readFirstLineBufferSync(filePath, maxBytes, !completeOnly)\n\t\t?.toString(\"utf8\")\n\t\t.replace(/\\n$/, \"\")\n\t\t.replace(/\\r$/, \"\");\n}\n\nexport async function* readLinesAsBuffers(\n\tfilePath: string,\n\toptions: { maxLineBytes?: number; includeNewline?: boolean; completeOnly?: boolean } = {},\n): AsyncGenerator<Buffer> {\n\tconst maxBytes = options.maxLineBytes ?? Infinity;\n\tif (maxBytes <= 0 || (maxBytes !== Infinity && !Number.isSafeInteger(maxBytes)))\n\t\tthrow new Error(\"Invalid line byte limit\");\n\tconst pendingParts: Buffer[] = [];\n\tlet pendingBytes = 0;\n\tfor await (const chunk of createReadStream(filePath)) {\n\t\tconst buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);\n\t\tlet start = 0;\n\t\twhile (start < buffer.length) {\n\t\t\tconst end = buffer.indexOf(0x0a, start);\n\t\t\tconst stop = end === -1 ? buffer.length : end + (options.includeNewline ? 1 : 0);\n\t\t\tconst part = buffer.subarray(start, stop);\n\t\t\tif (pendingBytes + part.length > maxBytes) throw new Error(\"Line byte limit exceeded\");\n\t\t\tif (end === -1) {\n\t\t\t\tpendingParts.push(part);\n\t\t\t\tpendingBytes += part.length;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tif (pendingParts.length > 0) {\n\t\t\t\tpendingParts.push(part);\n\t\t\t\tconst line = Buffer.concat(pendingParts, pendingBytes + part.length);\n\t\t\t\tpendingParts.length = 0;\n\t\t\t\tpendingBytes = 0;\n\t\t\t\tyield line;\n\t\t\t} else yield part;\n\t\t\tstart = end + 1;\n\t\t}\n\t}\n\tif (pendingParts.length > 0 && !options.completeOnly) yield Buffer.concat(pendingParts, pendingBytes);\n}\n"]}
+{"version":3,"file":"file-lines.d.ts","sourceRoot":"","sources":["../../src/utils/file-lines.ts"],"names":[],"mappings":"AAEA,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAY,EACpB,eAAe,UAAQ,GACrB,MAAM,GAAG,SAAS,CAsBpB;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAY,EAAE,YAAY,UAAQ,GAAG,MAAM,GAAG,SAAS,CAKlH;AAED,wBAAuB,kBAAkB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvF,cAAc,CAAC,MAAM,CAAC,CAmCxB","sourcesContent":["import { closeSync, createReadStream, openSync, readSync } from \"node:fs\";\n\nexport function readFirstLineBufferSync(\n\tfilePath: string,\n\tmaxBytes = 64 * 1024,\n\tallowIncomplete = false,\n): Buffer | undefined {\n\tconst fd = openSync(filePath, \"r\");\n\tconst chunks: Buffer[] = [];\n\tlet position = 0;\n\ttry {\n\t\tconst buffer = Buffer.alloc(1024);\n\t\twhile (position < maxBytes) {\n\t\t\tconst count = readSync(fd, buffer, 0, Math.min(buffer.length, maxBytes - position), position);\n\t\t\tif (count === 0) break;\n\t\t\tconst chunk = buffer.subarray(0, count);\n\t\t\tconst newline = chunk.indexOf(0x0a);\n\t\t\tif (newline !== -1) {\n\t\t\t\tchunks.push(Buffer.from(chunk.subarray(0, newline + 1)));\n\t\t\t\treturn Buffer.concat(chunks);\n\t\t\t}\n\t\t\tchunks.push(Buffer.from(chunk));\n\t\t\tposition += count;\n\t\t}\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\treturn allowIncomplete && chunks.length > 0 ? Buffer.concat(chunks) : undefined;\n}\n\nexport function readFirstLineSync(filePath: string, maxBytes = 64 * 1024, completeOnly = false): string | undefined {\n\treturn readFirstLineBufferSync(filePath, maxBytes, !completeOnly)\n\t\t?.toString(\"utf8\")\n\t\t.replace(/\\n$/, \"\")\n\t\t.replace(/\\r$/, \"\");\n}\n\nexport async function* readLinesAsBuffers(\n\tfilePath: string,\n\toptions: { maxLineBytes?: number; includeNewline?: boolean; completeOnly?: boolean } = {},\n): AsyncGenerator<Buffer> {\n\tconst maxBytes = options.maxLineBytes ?? Infinity;\n\tif (maxBytes <= 0 || (maxBytes !== Infinity && !Number.isSafeInteger(maxBytes)))\n\t\tthrow new Error(\"Invalid line byte limit\");\n\tconst pendingParts: Buffer[] = [];\n\tlet pendingBytes = 0;\n\tfor await (const chunk of createReadStream(filePath)) {\n\t\tconst buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);\n\t\tlet start = 0;\n\t\twhile (start < buffer.length) {\n\t\t\tconst end = buffer.indexOf(0x0a, start);\n\t\t\tconst stop = end === -1 ? buffer.length : end + (options.includeNewline ? 1 : 0);\n\t\t\tconst part = buffer.subarray(start, stop);\n\t\t\tif (pendingBytes + part.length > maxBytes) throw new Error(\"Line byte limit exceeded\");\n\t\t\tif (end === -1) {\n\t\t\t\tpendingParts.push(part);\n\t\t\t\tpendingBytes += part.length;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tif (pendingParts.length > 0) {\n\t\t\t\tpendingParts.push(part);\n\t\t\t\tconst line = Buffer.concat(pendingParts, pendingBytes + part.length);\n\t\t\t\tpendingParts.length = 0;\n\t\t\t\tpendingBytes = 0;\n\t\t\t\tyield line;\n\t\t\t} else yield part;\n\t\t\tstart = end + 1;\n\t\t}\n\t}\n\tif (pendingParts.length > 0 && !options.completeOnly) {\n\t\tconst line = Buffer.concat(pendingParts, pendingBytes);\n\t\tpendingParts.length = 0;\n\t\tpendingBytes = 0;\n\t\tyield line;\n\t}\n}\n"]}

package/dist/utils/file-lines.js

@@ -62,7 +62,11 @@ export async function* readLinesAsBuffers(filePath, options = {}) {
             start = end + 1;
         }
     }
-    if (pendingParts.length > 0 && !options.completeOnly)
-        yield Buffer.concat(pendingParts, pendingBytes);
+    if (pendingParts.length > 0 && !options.completeOnly) {
+        const line = Buffer.concat(pendingParts, pendingBytes);
+        pendingParts.length = 0;
+        pendingBytes = 0;
+        yield line;
+    }
 }
 //# sourceMappingURL=file-lines.js.map