@r1z4x/tezgah 1.6.0 → 1.7.0

package/hooks/tezgah_task.py

@@ -42,7 +42,14 @@ when the tree was clean, or `pending <sha>` when it was not, `<sha>` being the
 reader of that form). The gate refuses a write in that phase only while the
 recorded sha is still HEAD and the tree is still dirty, so the commit its refusal
 names clears it by itself.
+
+The slice journal lives here too (`open_slice` ... `slice_lines`): one row per
+delegated slice in `<main checkout>/.tezgah/slices/slices.db`, written by
+the post-tool path on a spawn call and by `tezgah-task slice`, so a parent
+crash, an omp `/clear`, a quota stop or a host switch loses no slice. They shell
+out to git and read omp transcripts; the Stop rule reads `pending` (fail open).
 """
+import contextlib
 import os
 import re
 
@@ -513,20 +520,60 @@ def match(rel, pattern):
     return re.fullmatch("".join(out), rel) is not None
 
 
-def relative(path, cwd, base):
+def relative(path, cwd, base, worktrees=False):
     """The realpath of `path` (absolute or relative to cwd) as a posix path
     relative to repo_root(cwd, base), or None when it resolves outside that root
-    (so an outside write can never be inside the allowlist)."""
+    (so an outside write can never be inside the allowlist).
+
+    With `worktrees`, a linked worktree of the same repository is that
+    repository, not outside it: the contract gives every writing slice its own
+    worktree, and an allowlist that could not name `hooks/a.py` there refused the
+    workflow it prescribes (three slices of plan 077 hit it). A path under such a
+    worktree answers relative to the worktree's top. Only the allowlist asks for
+    this (`hooks/tezgah_gate.py::task_reason`); the record and workspace rules
+    keep the main-root reading, so their decisions do not move. The test is
+    fork-free and only a path already outside the root pays for it; a worktree of
+    another repository is still outside."""
     root = repo_root(cwd, base)
+    path = os.path.expanduser(path)  # a host may spell it `~/...`
     real = os.path.realpath(path if os.path.isabs(path) else os.path.join(cwd, path))
     if real == root or not _under(real, root):
-        # the root itself is not a path inside the root: an allowlist is about
-        # files under it, so this is a None like any other, and every caller
-        # fails in the refusing direction
-        return None
+        top = _sibling_worktree(real, root) if worktrees else None
+        if top is None or real == top:
+            # the root itself is not a path inside the root: an allowlist is
+            # about files under it, so this is a None like any other, and every
+            # caller fails in the refusing direction
+            return None
+        root = top
     return real[len(root) + 1:].replace(os.sep, "/")
 
 
+def _sibling_worktree(real, root):
+    """The top of the linked worktree holding `real` when it is a checkout of the
+    repository `root` is a checkout of, else None.
+
+    The worktree's admin directory has to point back at it (`<admin>/gitdir` is
+    `<top>/.git`, which git always writes): a `.git` file planted anywhere that
+    names a real admin directory would otherwise make any directory a sibling."""
+    from tezgah_paths import linked_main, worktree_top
+    top = worktree_top(real)
+    if top is None:
+        return None
+    main = linked_main(root) or root
+    if linked_main(top) != os.path.realpath(main):
+        return None
+    try:
+        with open(os.path.join(top, ".git"), encoding="utf-8") as fh:
+            admin = fh.readline().strip()[len("gitdir:"):].strip()
+        admin = os.path.normpath(os.path.join(top, admin))
+        with open(os.path.join(admin, "gitdir"), encoding="utf-8") as fh:
+            back = fh.readline().strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+    back = os.path.normpath(os.path.join(admin, back))
+    return top if os.path.realpath(back) == os.path.join(top, ".git") else None
+
+
 def set_fields(path, **fields):
     """Rewrite these frontmatter keys in the plan file in place: replace the
     `key: value` line when present, insert it before the closing `---` when not.
@@ -570,3 +617,865 @@ def _field_lines(key, value):
     if value is None or value == "":
         return [key + ":"]
     return ["%s: %s" % (key, value)]
+
+
+def _lines(path):
+    with open(path, "r", encoding="utf-8") as fh:
+        return fh.read().split("\n")
+
+
+def _write_lines(path, lines):
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))
+
+
+def set_box(path, line, checked):
+    """Set the `- [ ]`/`- [x]` box on 1-based `line` (an acceptance item's
+    `line`). Raises OSError."""
+    lines = _lines(path)
+    lines[line - 1] = re.sub(r"- \[[ xX]\]", "- [x]" if checked else "- [ ]",
+                             lines[line - 1], count=1)
+    _write_lines(path, lines)
+
+
+def set_section(path, heading, body):
+    """Replace the body of the last `## <heading>` section - the newest, since
+    a plan appends a dated `## State (...)` - with `body` and one blank line.
+    Returns False, writing nothing, when the plan has no such section. Raises
+    OSError."""
+    lines = _lines(path)
+    heads = [i for i, line in enumerate(lines)
+             if re.match(r"## %s(\s|$)" % re.escape(heading), line.strip())]
+    if not heads:
+        return False
+    start = heads[-1] + 1
+    end = next((i for i in range(start, len(lines))
+                if lines[i].lstrip().startswith("## ")), len(lines))
+    lines[start:end] = body.strip("\n").split("\n") + [""]
+    _write_lines(path, lines)
+    return True
+
+
+# ---------------------------------------------------------------- slice journal
+#
+# One row per delegated slice in `<main checkout>/.tezgah/slices/slices.db`,
+# so a parent crash, an omp `/clear`, a quota stop or a model or host switch
+# loses no slice: the record names the brief, the worktree and branch it works
+# in, and how it ended. Written by the post-tool path on a spawn call
+# (`note_spawn`) and by `tezgah-task slice`; read by the context line
+# (`slice_lines`), the Stop rule and `tezgah-task slice reconcile|resume|stats`.
+# Every reader fails open: an unreadable record is skipped, never a refusal.
+# These functions shell out to git; none of them is on the gate's write path.
+
+SLICE_KINDS = ("agent", "job")
+SLICE_HOSTS = ("omp", "claude", "codex", "cursor", "opencode", "dsh")
+# `stale`: no terminal status was observed within SLICE_IDLE_SECONDS - a host
+# that reports none (Codex `spawn_agent` returns at once and tezgah sees no child
+# event) or a child that died without writing its end. It leaves the pending
+# list without being read as finished or as failed.
+SLICE_STATUSES = ("open", "done", "stopped", "resumed", "stale")
+SLICE_CLOSED = ("done", "stopped", "resumed", "stale")
+SLICE_IDLE_SECONDS = 6 * 3600
+FAILURES = ("quota", "rate_limit", "aborted", "timeout", "cut_off", "error")
+SLICE_BRIEF = 4000
+SLICE_LINE = 160
+SLICE_TAIL = 64 * 1024
+_SLICE_ID = re.compile(r"[^A-Za-z0-9._-]+")
+# Failure classes, first match wins, in this order. The table moved here from
+# the research line's measure (data/E2-subagent-stops/measure.py::CLASSES) and
+# was narrowed to the classes a lever exists for (`tezgah-task slice stats`).
+_CLASSES = (
+    ("rate_limit", re.compile(r"\b429\b|rate[ _-]?limit", re.I)),
+    ("quota", re.compile(r"quota|key limit exceeded|usage limit|"
+                         r"\b40[23]\b.*\blimit|\blimit\b.*\b40[23]\b", re.I)),
+    ("aborted", re.compile(r"abort|cancell?ed", re.I)),
+    ("timeout", re.compile(r"timed out|timeout", re.I)),
+    ("cut_off", re.compile(r"max[ _]turns|max_tokens|cut off|context[ _]length",
+                           re.I)),
+)
+
+
+def _now():
+    import time
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _git(cwd, *args):
+    """One git command's stdout in `cwd`, or None when git cannot answer."""
+    import subprocess
+    try:
+        out = subprocess.run(["git", "-C", cwd] + list(args), capture_output=True,
+                             text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip() if out.returncode == 0 else None
+
+
+def _journal_root(root):
+    """The main checkout of `root`'s repository: every worktree of one repository
+    writes one journal, so a slice opened from a worktree is still found from the
+    main checkout the parent session runs in."""
+    from tezgah_paths import linked_main
+    real = os.path.realpath(root)
+    return linked_main(real) or real
+
+
+def slice_dir(root):
+    """`<main checkout>/.tezgah/slices`, the one directory the records live in."""
+    return os.path.join(_journal_root(root), ".tezgah", "slices")
+
+
+def _digest(text):
+    import hashlib
+    return hashlib.sha1(text.encode("utf-8", "replace")).hexdigest()[:12]
+
+
+def slice_id(name, brief=""):
+    """A record id: `name` cut to [A-Za-z0-9._-] and 80 characters, else the
+    first 12 hex digits of the brief's sha1 - so a re-dispatch of the same brief
+    re-opens the same record and counts an attempt."""
+    sid = _SLICE_ID.sub("-", str(name or "")).strip("-.")[:80]
+    return sid or _digest(brief)
+
+
+# The journal is one SQLite file opened like the taste store
+# (`tezgah_store.connect`: WAL, a busy timeout, 0600). One JSON file per record
+# piled up a file per subagent in every repository (owner, 2026-10-11). `row`
+# is the record as JSON; `parent`, `status` and `updated` are the columns a
+# reader filters and sorts on, and `seq` orders two writes in one second.
+SLICE_DB = "slices.db"
+SLICE_SCHEMA = """
+CREATE TABLE IF NOT EXISTS slices (id TEXT PRIMARY KEY, parent TEXT NOT NULL,
+                                   status TEXT NOT NULL, updated TEXT NOT NULL,
+                                   seq INTEGER NOT NULL, row TEXT NOT NULL);
+"""
+
+
+@contextlib.contextmanager
+def _journal(root, create=True):
+    """The journal database of `root`'s repository, the `*.json` records an
+    older release wrote imported first (`_import_json`). With `create` False it
+    yields None where neither the database nor an old record exists, so a read
+    leaves no file behind. The directory carries a `.gitignore` of `*`: the
+    records are runtime state, never part of the private `.tezgah` history."""
+    import glob
+    import tezgah_store
+    folder = slice_dir(root)
+    path = os.path.join(folder, SLICE_DB)
+    if not create and not os.path.exists(path) and not glob.glob(
+            os.path.join(folder, "*.json")):
+        yield None
+        return
+    os.makedirs(folder, mode=0o700, exist_ok=True)
+    ignore = os.path.join(folder, ".gitignore")
+    if not os.path.exists(ignore):
+        with open(ignore, "w", encoding="utf-8") as fh:
+            fh.write("*\n")
+    conn = tezgah_store.connect(path, SLICE_SCHEMA, version=1)
+    try:
+        _import_json(conn, folder)
+        yield conn
+    finally:
+        conn.close()
+
+
+def _import_json(conn, folder):
+    """Bring the one-file-per-record journal into the table, then delete each
+    file it took. A file whose `updated` is newer than the row replaces it - an
+    older release still running writes files beside the database - and an
+    older one leaves the row alone. A file that does not parse, or whose id is
+    not a string, stays where it is. With no old file, one glob."""
+    import glob
+    import json
+    for path in glob.glob(os.path.join(folder, "*.json")):
+        try:
+            with open(path, encoding="utf-8") as fh:
+                rec = json.load(fh)
+        except (OSError, ValueError):
+            continue
+        if not isinstance(rec, dict) or not isinstance(rec.get("id"), str) \
+                or not rec["id"]:
+            continue
+        held = conn.execute("SELECT updated FROM slices WHERE id = ?",
+                            (rec["id"],)).fetchone()
+        if held is None or str(rec.get("updated") or "") > held[0]:
+            _put(conn, rec)
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+
+
+def _put(conn, rec):
+    """Upsert one record."""
+    import json
+    conn.execute(
+        "INSERT OR REPLACE INTO slices (id, parent, status, updated, seq, row) "
+        "VALUES (?, ?, ?, ?, (SELECT COALESCE(MAX(seq), 0) + 1 FROM slices), ?)",
+        (rec["id"], str(rec.get("parent") or ""), str(rec.get("status") or ""),
+         str(rec.get("updated") or ""), json.dumps(rec, sort_keys=True)))
+
+
+def _row(text):
+    import json
+    try:
+        rec = json.loads(text)
+    except ValueError:
+        return None
+    return rec if isinstance(rec, dict) and rec.get("id") else None
+
+
+def _read_record(root, sid):
+    """The record `sid`, or None; a journal that cannot be opened reads as none."""
+    import tezgah_store
+    try:
+        with _journal(root, create=False) as db:
+            hit = db and db.execute("SELECT row FROM slices WHERE id = ?",
+                                    (slice_id(sid),)).fetchone()
+    except tezgah_store.ERRORS:
+        return None
+    return _row(hit[0]) if hit else None
+
+
+def _write_record(root, rec):
+    """Write one record (one upsert statement) and return it. A database that
+    cannot be opened or written raises OSError, the error every caller already
+    handles (`tezgah-task slice` prints it, the hooks swallow it)."""
+    import tezgah_store
+    try:
+        with _journal(root) as db:
+            _put(db, rec)
+    except tezgah_store.ERRORS as exc:
+        raise OSError("slice journal %s: %s" % (slice_dir(root), exc)) from exc
+    return rec
+
+
+def _own_id(root, base, brief, parent):
+    """The record id a spawn of `base` opens: `base` itself, unless another
+    session holds that record under another brief. Then it is this session's
+    own record of that name, else `base-<digest6>` of the brief, so another
+    session's stopped slice stays its owner's (research orchestrator-flow-audit
+    S7). A same-brief re-dispatch from another session still re-opens `base`."""
+    held = _read_record(root, base)
+    if (held is None or not parent or not brief
+            or held.get("parent") in ("", None, parent)
+            or held.get("brief") == brief):
+        return base
+    own = next((r["id"] for r in slices(root) if r.get("parent") == parent
+                and (r.get("name") or r["id"]) == base), None)
+    return own or "%s-%s" % (base, _digest(brief)[:6])
+
+
+def find_slice(root, ref, session=None):
+    """The record `ref` names for `tezgah-task slice done|stop|resume`. An
+    exact id answers whatever session owns it: an id is unambiguous, and it is
+    what `slice reconcile` and the review guard print, so a crashed session's
+    slice stays reachable. A bare spawned `name` is a lookup: with `session`
+    (TEZGAH_SESSION), the newest record of that name the session spawned or no
+    session owns; without one, the one record of that name. None when nothing
+    answers."""
+    ref = slice_id(ref)
+    recs = slices(root)
+    exact = next((r for r in recs if r["id"] == ref), None)
+    if exact or session:
+        return exact or next((r for r in recs if r.get("name") == ref
+                              and r.get("parent") in (session, "", None)), None)
+    named = [r for r in recs if r.get("name") == ref]
+    return named[0] if len(named) == 1 else None
+
+
+def _worktree_in(root, *texts):
+    """The linked worktree of this repository the first of `texts` that names
+    one names, else "": a slice's own task before the batch's shared context
+    (which may list every slice's worktree), the one named last in a text, and
+    on a tie the longer path, since `.../a` is found inside `.../a-b` at the
+    same place. What reconcile, resume, the board and merge-plan read."""
+    from tezgah_paths import worktrees
+    trees = worktrees(root)[1:]
+    for text in texts:
+        found = [p for p in trees if text and p in text]
+        if found:
+            return max(found, key=lambda p: (text.rfind(p), len(p)))
+    return ""
+
+
+def _named_worktree(root, *texts):
+    """(worktree, branch) for the linked worktree `_worktree_in` reads off
+    `texts`, else ("", "")."""
+    top = _worktree_in(root, *texts)
+    return (top, _git(top, "symbolic-ref", "-q", "--short", "HEAD") or "") if top else ("", "")
+
+
+# Where a brief says its slice works: a `Worktree:`, `Checkout` or `Cwd:` line
+# opening with an absolute path. A path merely mentioned - a worktree to remove,
+# a sibling's tree, a file to read - is no declaration (review of S6, F2). Only
+# the main-checkout refusal reads it (`tezgah_gate.lease_reason`).
+_DECLARED = re.compile(r"(?im)^[ \t>#*_-]*(?:worktree|checkout|cwd)\b[*_]*[ \t]*:?"
+                       r"[*_]*[ \t]*`?(/[^\s`'\"()<>,;]+)")
+
+
+def _declared_in(root, *texts):
+    """The linked worktree of this repository the first of `texts` that
+    declares a checkout of it declares, else "": a slice's own task before the
+    batch's shared context, the last declaration in a text. A declared main
+    checkout is none - an integrator works there."""
+    from tezgah_paths import worktrees
+    trees = worktrees(root)
+    for text in texts:
+        found = [os.path.realpath(p.rstrip("/.:")) for p in _DECLARED.findall(text or "")]
+        found = [p for p in found if p in trees]
+        if found:
+            return found[-1] if found[-1] != trees[0] else ""
+    return ""
+
+
+# `Owns:` in a slice's own task: the repository-relative globs only that slice
+# writes while its record is open (research orchestrator-flow-audit S6, pick
+# V2). The gate refuses a sibling's write into them (`tezgah_gate.lease_reason`).
+# The globs follow on the line, split on commas and spaces, or - with nothing
+# after the colon - as the `- glob` list items under it. Markdown emphasis and
+# backticks are dropped; an absolute glob under the slice's checkout is cut to it.
+_OWNS = re.compile(r"(?i)^[ \t>#*_-]*owns[*_]*[ \t]*:[*_]*[ \t]*(.*)$")
+_LIST_ITEM = re.compile(r"^[ \t>]*(?:[-*+]|\d+[.)])[ \t]+(.+)$")
+
+
+def owned_globs(text, tops=()):
+    """The `Owns:` globs `text` names, in order, each once."""
+    found, lines = [], (text or "").splitlines()
+    for i, line in enumerate(lines):
+        hit = _OWNS.match(line)
+        if not hit:
+            continue
+        if hit.group(1).strip():
+            found.append(hit.group(1))
+            continue
+        for item in lines[i + 1:]:
+            listed = _LIST_ITEM.match(item)
+            if not listed:
+                break
+            found.append(listed.group(1))
+    out = []
+    for line in found:
+        for glob in re.split(r"[\s,]+", line.replace("`", "")):
+            glob = glob.rstrip(".;")
+            top = next((t for t in tops if t and glob.startswith(t + "/")), "")
+            glob = glob[len(top) + 1:] if top else glob
+            if glob and glob not in out:
+                out.append(glob)
+    return out
+
+
+def slice_of(root, parent, name):
+    """The newest record `parent` spawned under `name` - a subagent's own
+    record, read from its `spawned` row (`tezgah_integrity.spawn_of`), or from
+    Claude's `agent_id`, which a background spawn stores as `child` - else
+    None. An exact name or child first; omp names a re-dispatch `<name>-2`, so
+    the bare name answers only after that."""
+    if not (parent and name):
+        return None
+    mine = [r for r in slices(root) if r.get("parent") == parent]
+    base = re.sub(r"-\d+$", "", name)
+    return (next((r for r in mine if (r.get("name") or r["id"]) == name
+                  or r.get("child") == name), None)
+            or next((r for r in mine if (r.get("name") or r["id"]) == base), None))
+
+
+def owner_of(root, path, parent, me):
+    """The open record of another writing slice `parent` spawned whose `owns`
+    matches the repository-relative `path`, else None; `me` is the writing
+    slice's id. A reader - an agent named for a read-only role - holds no
+    lease, whatever `Owns:` line its task quotes. A hit re-reads after
+    `pending`, which closes an omp sibling whose child transcript ended, so a
+    finished owner frees its files."""
+    def held():
+        return next((r for r in slices(root) if parent and r.get("parent") == parent
+                     and r.get("status") == "open" and r["id"] != me
+                     and not _READ_ONLY_AGENT.search(r.get("agent") or "")
+                     and any(match(path, g) for g in r.get("owns") or ())), None)
+    if held() is None:
+        return None
+    pending(root)
+    return held()
+
+
+def close_child(root, parent, child):
+    """Close as done the open record `parent` spawned whose `child` is the
+    host's id of a background child that just ended (Claude's SubagentStop),
+    and return it; None when no record holds it."""
+    rec = next((r for r in slices(root) if parent and child and r.get("parent") == parent
+                and r.get("child") == child and r.get("status") == "open"), None)
+    return close_slice(root, rec["id"], "done") if rec else None
+
+
+BOARD_LINES = 12
+
+
+def board(root, parent=None, limit=BOARD_LINES):
+    """One bounded line (SLICE_LINE) per open record `parent` spawned - every
+    open record without one - newest first, at most `limit` and a count of the
+    rest: what each slice owns, where it works and its last commit. A pull
+    read: siblings see each other's leases here instead of by message."""
+    recs = [r for r in pending(root) if r.get("status") == "open"
+            and r.get("kind") != "job" and (parent is None or r.get("parent") == parent)]
+    out = []
+    for rec in recs[:limit]:
+        tree = rec.get("worktree") or ""
+        head = _git(tree, "log", "-1", "--format=%h") if tree and os.path.isdir(tree) else None
+        out.append(_cut("- %s (%s/%s) owns %s; worktree %s on %s @ %s" % (
+            rec.get("name") or rec["id"], rec.get("host") or "?", rec.get("agent") or "?",
+            ", ".join(rec.get("owns") or ()) or "nothing declared", tree or "none",
+            rec.get("branch") or "?", head or "?")))
+    if len(recs) > limit:
+        out.append("- %d more open slice(s)" % (len(recs) - limit))
+    return out
+
+
+# An agent whose name reads as a read-only role shares a worktree freely: a
+# reviewer panel on one slice's checkout is the allowed case (research
+# orchestrator-flow-audit S6, finding 5). A brief with `Owns:` writes whatever
+# its agent is called.
+_READ_ONLY_AGENT = re.compile(r"review|explor|research|scout|audit|critic|judge", re.I)
+SHARED_WORKTREE = (
+    "tezgah: writing slices %s all name worktree %s. Every writing slice gets its own "
+    "branch and checkout (`orca worktree create` inside Orca, else `git worktree "
+    "add`): two slices in one checkout overwrite each other's edits.")
+
+
+def _writing(agent, owns):
+    return bool(owns) or not _READ_ONLY_AGENT.search(agent or "")
+
+
+def _writes(rec):
+    """A writing record: its own task's `Owns:`, else an agent not named for a
+    read-only role. A reviewer whose lease came from a shared brief is not one."""
+    return _writing(rec.get("agent"), owned_globs(rec.get("task") or ""))
+
+
+def worktree_clash(root, tool, inp, parent=""):
+    """SHARED_WORKTREE when two writing slices - of this spawn call, or this
+    call and an open record `parent` spawned - name one worktree, else None.
+    Each task's own text decides its worktree; one that names none takes the
+    shared context's, which is how ten slices landed in one checkout."""
+    main = _journal_root(root)
+    seen = {}
+    for rec in slices(root):
+        if parent and rec.get("parent") == parent and rec.get("status") == "open" \
+                and rec.get("worktree") and _writes(rec):
+            seen.setdefault(rec["worktree"], set()).add(rec.get("name") or rec["id"])
+    context = str(inp.get("context") or "").strip() if isinstance(inp, dict) else ""
+    for sid, agent, brief in spawned(tool, inp):
+        task = brief[len(context):] if context else brief
+        tree = _worktree_in(main, task, brief)
+        if tree and _writing(agent, owned_globs(task)):
+            seen.setdefault(tree, set()).add(sid)
+    clash = sorted((t, sorted(n)) for t, n in seen.items() if len(n) > 1)
+    return SHARED_WORKTREE % (", ".join(clash[0][1]), clash[0][0]) if clash else None
+
+
+def open_slice(root, sid, *, kind="agent", host="", agent="", brief="", parent="",
+               cwd="", repo="", task="", child=""):
+    """Open (or re-open) the record `sid` and return it. The worktree and branch
+    are the ones the slice's own task names (else the brief, `_worktree_in`);
+    `declared` is the worktree a `Worktree:`/`Checkout`/`Cwd:` line declares
+    (`_declared_in`); the base is the main checkout's HEAD, and `owns` holds the
+    `Owns:` globs of the task (else the brief, `owned_globs`). A re-open
+    of an existing id counts one more attempt, sets the status back to open and
+    clears the failure; a field the new call leaves empty keeps its old value.
+    A record another session holds under another brief is not re-opened: the
+    spawn gets its own id (`_own_id`), and `name` keeps the spawned name.
+    `repo` names the repository the slice works in when that is not this
+    journal's (`_brief_repo`); `child` is the host's id for the running child
+    (Claude's background `agentId`), the key its own writes carry."""
+    base = slice_id(sid, brief)
+    main = _journal_root(root)
+    own = task or brief or ""
+    brief = (brief or "")[:SLICE_BRIEF]
+    now = _now()
+    sid = _own_id(root, base, brief, parent)
+    rec = _read_record(root, sid)
+    if rec is None:
+        rec = {"id": sid, "name": base, "kind": kind if kind in SLICE_KINDS else "agent",
+               "host": host, "agent": agent, "brief": brief, "parent": parent,
+               "cwd": cwd, "repo": repo, "worktree": "", "branch": "", "attempts": 1,
+               "opened": now, "child": child}
+    else:
+        rec["attempts"] = int(rec.get("attempts") or 0) + 1
+        if parent and parent != rec.get("parent"):
+            # a re-dispatch from another session (after a /clear, a crash, a
+            # resume) writes its child under that session's directory: the old
+            # one holds the first run, whose end must not close this record
+            rec["transcript_dir"] = ""
+        for key, value in (("host", host), ("agent", agent), ("brief", brief),
+                           ("parent", parent), ("cwd", cwd), ("repo", repo),
+                           ("child", child)):
+            if value:
+                rec[key] = value
+    if task:  # the slice's own task, without a batch's shared context
+        rec["task"] = task[:SLICE_BRIEF]
+    if brief or not rec.get("worktree"):
+        rec["worktree"], rec["branch"] = _named_worktree(main, task, rec.get("brief"))
+        rec["declared"] = _declared_in(main, task, rec.get("brief"))
+    if own:
+        rec["owns"] = owned_globs(own, (rec["worktree"], main))
+    if rec.get("host") == "omp" and rec.get("parent") and not rec.get("transcript_dir"):
+        # one glob over every omp project at open, so `pending` - run on every
+        # prompt and Stop - never globs (40 ms on 1393 project dirs, measured)
+        rec["transcript_dir"] = _omp_session_dir(rec["parent"]) or ""
+    # the plan whose task was active when the slice opened: the review guard
+    # reads its own plan's records only
+    rec["plan"] = (active(main, main) or {}).get("id") or rec.get("plan") or ""
+    rec.update(base=_git(main, "rev-parse", "HEAD") or "", status="open",
+               failure="", updated=now)
+    return _write_record(root, rec)
+
+
+def close_slice(root, sid, status, failure="", stop=None):
+    """Close the record `sid` as done, stopped or resumed; None when it has none.
+    A stopped record takes `failure` (a FAILURES class or ""); done and resumed
+    keep the class the slice stopped with, so the stats still count the event.
+    A quota or rate-limit stop whose message `stop` ({errorMessage, provider,
+    model, default}) names its family holds that family down
+    (`tezgah_models.note_limit`; a rate limit briefly);
+    that push fails open."""
+    if status not in SLICE_CLOSED:
+        raise ValueError("status %r is not one of %s" % (status, ", ".join(SLICE_CLOSED)))
+    rec = _read_record(root, sid)
+    if rec is None:
+        return None
+    if status == "stopped" or failure:
+        rec["failure"] = failure if failure in FAILURES else ""
+    rec.update(status=status, updated=_now())
+    if failure in ("quota", "rate_limit") and isinstance(stop, dict):
+        try:
+            import tezgah_models
+            tezgah_models.note_limit(
+                stop.get("errorMessage") or "", stop.get("provider") or "",
+                stop.get("model") or "", transient=failure == "rate_limit",
+                default=stop.get("default") or "")
+        except Exception:  # noqa: BLE001 - health is advice: the close still lands
+            pass
+    return _write_record(root, rec)
+
+
+def slices(root):
+    """Every readable record, newest `updated` first (the later write first on a
+    tie); a row that does not parse, or a journal that cannot be opened, is
+    skipped - readers fail open."""
+    import tezgah_store
+    try:
+        with _journal(root, create=False) as db:
+            rows = db.execute("SELECT row FROM slices ORDER BY updated DESC, "
+                              "seq DESC").fetchall() if db else []
+    except tezgah_store.ERRORS:
+        return []
+    return [rec for rec in (_row(r[0]) for r in rows) if rec]
+
+
+def classify(text):
+    """The failure class of an error or result text: rate_limit, quota, aborted,
+    timeout, cut_off, else error for any other non-empty text, "" for none."""
+    text = str(text or "").strip()
+    if not text:
+        return ""
+    for name, pattern in _CLASSES:
+        if pattern.search(text):
+            return name
+    return "error"
+
+
+def _brief(*parts):
+    return "\n\n".join(str(p).strip() for p in parts if str(p or "").strip())
+
+
+def spawned(tool, inp):
+    """[(id, agent, brief)] for one spawn call's input, [] for any other tool.
+    omp `task` carries a batch ({tasks: [{name, agent, task}], context}, brief =
+    context + task); Claude, dsh and Cursor `Agent`/`Task` and opencode `task`
+    carry one ({description, prompt, subagent_type}); Codex `spawn_agent` carries
+    {task_name, message|prompt, agent_type|agent} - its `task_name` is the id the
+    user addresses the child by."""
+    if not isinstance(inp, dict):
+        return []
+    name = str(tool or "").lower()
+    out = []
+    if name == "task" and isinstance(inp.get("tasks"), list):
+        context = inp.get("context") or ""
+        for item in inp["tasks"]:
+            if not isinstance(item, dict):
+                continue
+            brief = _brief(context, item.get("task") or "")
+            out.append((slice_id(item.get("name"), brief), str(item.get("agent") or ""),
+                        brief))
+    elif name in ("task", "agent"):
+        brief = _brief(inp.get("description") or "", inp.get("prompt") or "")
+        out.append((slice_id(inp.get("name"), brief),
+                    str(inp.get("subagent_type") or ""), brief))
+    elif name == "spawn_agent":
+        brief = str(inp.get("message") or inp.get("prompt") or "")
+        out.append((slice_id(inp.get("task_name") or inp.get("name"), brief),
+                    str(inp.get("agent_type") or inp.get("agent") or ""), brief))
+    return [row for row in out if row[2]]
+
+
+def note_spawn(cwd, session_id, host, tool, inp, failed=None, result_text="",
+               child=""):
+    """Open one record per slice a spawn call started, and return them. A host
+    that runs the subagent synchronously (Claude's PostToolUse on Agent/Task)
+    passes `failed` as a bool and the record closes at once: stopped with the
+    class of `result_text` (error when it names none), else done. No-op ([])
+    under `slices-off` or outside a git checkout. The record stays in cwd's
+    journal, the one the owner's Stop rule, resume block and review guard
+    read, and names the repository its brief works in as `repo`
+    (`_brief_repo`) when that is another one. `child` is the id the host
+    returned for a background child (Claude's `agentId`)."""
+    from tezgah_paths import _toplevel, off
+    if off("slices-off") or not cwd:
+        return []
+    root = _toplevel(os.path.realpath(cwd))
+    if not root:
+        return []
+    here = _journal_root(root)
+    out = []
+    context = str(inp.get("context") or "").strip() if isinstance(inp, dict) else ""
+    for sid, agent, brief in spawned(tool, inp):
+        repo = _brief_repo(brief, here)
+        rec = open_slice(root, sid, host=host, agent=agent, brief=brief,
+                         parent=session_id or "", cwd=cwd,
+                         repo="" if repo == here else repo,
+                         task=brief[len(context):].strip() if context else brief,
+                         child=child)
+        if failed is True:
+            # a Claude subagent runs on Anthropic unless its model names another
+            # vendor; another host's input may name a model
+            stop = {"errorMessage": result_text, "model": str(inp.get("model") or ""),
+                    "default": "anthropic" if host == "claude" else ""}
+            rec = close_slice(root, rec["id"], "stopped",
+                              classify(result_text) or "error", stop)
+        elif failed is False:
+            rec = close_slice(root, rec["id"], "done")
+        out.append(rec)
+    return out
+
+
+# An absolute path in a brief: a slash after a space, a quote or a bracket, up
+# to the next space, quote, bracket or separator.
+_ABS_PATH = re.compile(r"(?<![\w.~/-])/[^\s'\"`<>()\[\]{},;|*?]+")
+
+
+def main_repo(path):
+    """The main checkout of the repository holding `path`, else None. A path
+    under a repository's own `.tezgah` - a private git repository of its own -
+    belongs to the repository around it, and a worktree to its main checkout."""
+    from tezgah_paths import _toplevel
+    top = _toplevel(os.path.realpath(path))
+    while top and os.path.basename(top) == ".tezgah":
+        top = _toplevel(os.path.dirname(top))
+    return _journal_root(top) if top else None
+
+
+def _brief_repo(brief, root):
+    """The main checkout of the one armed repository every absolute path the
+    brief names lies in, else `root`. A brief naming two repositories, or none,
+    keeps `root` (research orchestrator-flow-audit S7, finding 2)."""
+    from tezgah_paths import root_for
+    found = set()
+    for path in _ABS_PATH.findall(brief or ""):
+        top = main_repo(path.rstrip(".:"))
+        if top and root_for(top):
+            found.add(top)
+    return found.pop() if len(found) == 1 else root
+
+
+def _omp_session_dir(parent):
+    """The omp session directory of parent session `parent`
+    (`~/.omp/agent/sessions/<project>/<stamp>_<parent>/`, one `<agent id>.jsonl`
+    per subagent), or None. One glob over every project, so it runs once per
+    record (`open_slice`), never per prompt."""
+    import glob
+    if not parent or "/" in parent or os.sep in parent:
+        return None
+    home = os.path.expanduser("~")
+    hits = glob.glob(os.path.join(home, ".omp", "agent", "sessions", "*",
+                                  "*_" + glob.escape(parent)))
+    return hits[0] if hits else None
+
+
+def _omp_transcript(rec):
+    """The newest omp child transcript of the record: omp names a re-dispatch of
+    the same agent name in one session `<name>-2.jsonl`, `<name>-3.jsonl`, so the
+    highest suffix is the attempt the record now tracks - reading `<name>.jsonl`
+    would close a re-opened record with the first run's end. None when the
+    record names no session directory or the directory holds no such file. The
+    file is named by the spawned `name`, which a record's own id may extend."""
+    folder, sid = rec.get("transcript_dir"), rec.get("name") or rec.get("id")
+    if not folder or not sid:
+        return None
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return None
+    best, rank = None, -1
+    attempt = re.compile(re.escape(sid) + r"(?:-(\d+))?\.jsonl")
+    for name in names:
+        hit = attempt.fullmatch(name)
+        n = int(hit.group(1) or 1) if hit else -1
+        if n > rank:
+            best, rank = os.path.join(folder, name), n
+    return best
+
+
+def _transcript_end(path):
+    """How an omp child transcript ended, read from its last SLICE_TAIL bytes:
+    ("stopped", class) for an error, abort or length stop on the last assistant
+    message, an error with that message third (`close_slice`'s `stop`);
+    ("done", "") once it yielded, stopped normally or exited; None while
+    it may still be running or cannot be read."""
+    import json
+    try:
+        with open(path, "rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            size = fh.tell()
+            fh.seek(max(0, size - SLICE_TAIL))
+            data = fh.read().decode("utf-8", "replace")
+    except OSError:
+        return None
+    rows = []
+    for line in data.splitlines():
+        try:
+            row = json.loads(line)
+        except ValueError:
+            continue  # the first line of a cut tail, or a torn last one
+        if isinstance(row, dict):
+            rows.append(row)
+    exited = yielded = False
+    for row in reversed(rows):
+        if row.get("type") == "custom" and row.get("customType") == "session_exit":
+            exited = True
+        msg = row.get("message") if isinstance(row.get("message"), dict) else None
+        if not msg:
+            continue
+        if msg.get("role") == "toolResult" and msg.get("toolName") in ("yield",
+                                                                         "submit_result"):
+            yielded = True
+        if msg.get("role") != "assistant":
+            continue
+        stop = msg.get("stopReason")
+        if stop == "error":
+            return "stopped", classify(msg.get("errorMessage")) or "error", msg
+        if stop == "aborted":
+            return "stopped", "aborted"
+        if stop == "length":
+            return "stopped", "cut_off"
+        if yielded or exited or stop == "stop":
+            return "done", ""
+        return None
+    return ("done", "") if yielded or exited else None
+
+
+# How long a `job` record stays pending: omp clamps a background call's
+# deadline to 3600 s, so a job opened longer ago has ended either way and its
+# line would only repeat itself on every prompt. Its result stays in the parent
+# transcript the record names, so it closes `stale`, not done.
+SLICE_JOB_SECONDS = 3600
+
+
+def _age(rec):
+    """Seconds since the record last changed (`updated`, else `opened`), or None
+    when neither reads as a record time."""
+    import calendar
+    import time
+    stamp = str(rec.get("updated") or rec.get("opened") or "")
+    try:
+        then = calendar.timegm(time.strptime(stamp, "%Y-%m-%dT%H:%M:%SZ"))
+    except ValueError:
+        return None
+    return time.time() - then
+
+
+def pending(root):
+    """The records still owed work - status open or stopped - newest first. An
+    omp record still open whose child transcript has ended is closed first:
+    stopped with its failure class, or done when it ended normally. An open
+    record nothing has moved for SLICE_IDLE_SECONDS (an omp child's transcript
+    included) - or a `job` past SLICE_JOB_SECONDS - closes `stale`. One stat and
+    at most one SLICE_TAIL read per open omp record."""
+    out = []
+    for rec in slices(root):
+        if rec.get("status") != "open":
+            if rec.get("status") == "stopped":
+                out.append(rec)
+            continue
+        idle, limit = _age(rec), SLICE_IDLE_SECONDS
+        if rec.get("kind") == "job":
+            limit = SLICE_JOB_SECONDS
+        elif rec.get("host") == "omp":
+            if not rec.get("transcript_dir") and idle is not None and idle < 600:
+                # the parent's directory did not exist yet when the record
+                # opened: one more glob while the record is young, then kept
+                found = _omp_session_dir(rec.get("parent"))
+                if found:
+                    rec["transcript_dir"] = found
+                    _write_record(root, rec)
+            path = _omp_transcript(rec)
+            end = _transcript_end(path) if path else None
+            if end:
+                rec = close_slice(root, rec["id"], *end) or rec
+            elif path:
+                try:
+                    import time
+                    idle = min(idle if idle is not None else 1e18,
+                               time.time() - os.stat(path).st_mtime)
+                except OSError:
+                    pass
+        if rec.get("status") == "open" and idle is not None and idle > limit:
+            rec = close_slice(root, rec["id"], "stale") or rec
+        if rec.get("status") in ("open", "stopped"):
+            out.append(rec)
+    return out
+
+
+def _cut(line, keep=""):
+    """`line` + `keep` cut to SLICE_LINE characters, the cut taken from `line` so
+    `keep` (the command that acts on the record) survives whole."""
+    room = SLICE_LINE - len(keep)
+    if len(line) > room:
+        line = line[:max(0, room - 3)] + "..."
+    return (line + keep)[:SLICE_LINE]
+
+
+def slice_line(rec):
+    """One bounded line (SLICE_LINE characters) for one record."""
+    sid = rec.get("id") or ""
+    status = rec.get("status") or ""
+    if rec.get("kind") == "job":
+        return _cut("- job %s %s: %s (parent session %s) - read its result there "
+                    "before re-running" % (sid, status,
+                                           " ".join(str(rec.get("brief") or "").split())[:60],
+                                           rec.get("parent") or "?"))
+    head = "- slice %s (%s/%s) %s%s attempts %s" % (
+        sid, rec.get("host") or "?", rec.get("agent") or "?", status,
+        (" " + rec["failure"]) if rec.get("failure") else "", rec.get("attempts") or 1)
+    tree = rec.get("worktree") or ""
+    if rec.get("repo"):
+        head += " (in %s)" % os.path.basename(rec["repo"])
+    if tree and os.path.isdir(tree):
+        head += " worktree %s @ %s" % (tree, _git(tree, "rev-parse", "--short", "HEAD") or "?")
+    return _cut(head, ": tezgah-task slice resume %s" % sid)
+
+
+def slice_lines(root, limit=3, session=None, others=False):
+    """One line per pending record, newest first, at most `limit` of them; with
+    `session`, only the records that session spawned (`parent`) or that no
+    session owns (one opened by hand with no `--parent`) - another session's
+    slices are its own to resume. With `others`, one closing line counts those
+    others, so a new session after a crash or a host switch still learns they
+    exist (the resume block asks for it, the per-prompt part does not)."""
+    recs = pending(root)
+    if session is None:
+        return [slice_line(rec) for rec in recs[:limit]]
+    mine = [r for r in recs if r.get("parent") in (session, "", None)]
+    out = [slice_line(rec) for rec in mine[:limit]]
+    if others and len(recs) > len(mine):
+        out.append("- %d pending slice(s) of other sessions: tezgah-task slice reconcile"
+                   % (len(recs) - len(mine)))
+    return out