@r1z4x/tezgah 1.6.0 → 1.7.0

package/hooks/tezgah_gate.py

@@ -108,6 +108,7 @@ from tezgah_integrity import (BASH_TOOLS, BEGAN_KIND, ENV_WORD, GIT_VALUE_OPTS,
                               prior_calls, scratch_target, shortcut_command,
                               shortcut_edit, turn_rows, verify_command,
                               write_texts)
+from tezgah_integrity import SUBAGENT_TOOLS, TODO_TOOLS, newest_todo, ready_heads
 from tezgah_paths import (CACHE, CONFIG_DIR, HOST_DIRS, OFF_DIRS, PLUGIN_ROOT,
                           REPO_MARKS, SWITCHES, cache_dir, fallback_cache,
                           linked_main, off, root_for, roots)
@@ -124,9 +125,9 @@ except ImportError:  # pragma: no cover - only on an integrity module without th
 try:  # The race rule reads the write history through tezgah_integrity; that
     # reader is newer than some checkouts of the module, and a missing name must
     # cost the rule, never the session (this import runs on every gated call).
-    from tezgah_integrity import writers_elsewhere
+    from tezgah_integrity import spawn_of, writers_elsewhere
 except ImportError:  # pragma: no cover - only on an integrity module without it
-    writers_elsewhere = None
+    spawn_of = writers_elsewhere = None
 
 try:  # The bytes a write is about to change. The snapshot module is newer than
     # some checkouts too, and a missing module must cost the snapshot, never the
@@ -896,11 +897,23 @@ RACE_WINDOW_MIN = 10
 # overwrite, so this rule cannot be a soft one.
 RACE_REFUSE = True
 RACE_DENY = (
-    "Concurrent write refused: session %s wrote this file within the last %d "
+    "Concurrent write refused: %s wrote this file within the last %d "
     "minutes, so the copy of %s in your context may already be stale. Re-read "
     "the file and re-apply your change to what is on disk now; if both sessions "
     "are editing it, say so and let one of them own the file rather than "
     "overwriting the other's work.")
+# How RACE_DENY names a writer, by its relation to this session
+# (tezgah_integrity._relation): the bare ledger id sent a model to the wrong
+# cause - it called an omp fork "a second window of the same session"
+# (research orchestrator-flow-audit S7, finding 4).
+RACE_WHO = {
+    "child": "your own subagent %s (ledger %s), not ended in the slice journal",
+    "parent": "your parent session (ledger %s)",
+    "sibling": "sibling subagent %s of your parent (ledger %s)",
+    "fork": "an omp fork of this session (ledger %s)",
+    "forked-from": "the session this one was forked from (ledger %s)",
+    "unrelated": "another, unrelated session %s",
+}
 # The file a write call names, per host dialect, plus the apply_patch headers
 # (tezgah_integrity.PATCH_FILE) for the dialect whose paths live in the body.
 # The race guard resolves each against the call's cwd to an absolute real path
@@ -911,8 +924,27 @@ RACE_DENY = (
 # tool device, never a file on disk. Deliberately a list, not `scheme://`: a
 # file reached through a URI scheme is still a file two sessions can race on.
 URI_CHANNEL = re.compile(
-    r"^(?:agent|xd|local|artifact|proc|skill|mcp|omp|issue|pr|history|ssh|cfg)://",
-    re.I)
+    r"^(?:agent|xd|local|artifact|proc|skill|mcp|omp|issue|pr|history|ssh|cfg|"
+    r"conflict)://", re.I)
+# The task rule's wider reading: ANY scheme. Its question is "is this a path in
+# the checkout", and a URI is not one - `tezgah_task.relative` would read
+# `xd://mcp__codegraph_explore` as a relative file and refuse a name that exists
+# nowhere (a user session, 2026-10-11: `xd://` and `conflict://` writes refused
+# as outside the allowlist).
+# `file://` is the one scheme that names a checkout file, so it stays guarded,
+# as the race rule already reads it.
+URI_TARGET = re.compile(r"^(?!file://)[A-Za-z][A-Za-z0-9+.-]*://", re.I)
+# A shell target still holding a variable or a substitution once write_paths
+# expanded what it could: the shell names the file at run time, the gate cannot.
+UNEXPANDED = re.compile(r"\$[A-Za-z_{(]|`")
+# One unexpanded piece of a shell target, for `known_tail`.
+UNEXPANDED_PIECE = re.compile(
+    r"\$\{[^}]*\}|\$\([^)]*\)|\$[A-Za-z_][A-Za-z0-9_]*|`[^`]*`")
+# `NAME=value` at a word start, and the `$NAME`/`${NAME}` a later word reads.
+SHELL_ASSIGN = re.compile(
+    r"(?:^|(?<=[\s;&|(]))([A-Za-z_][A-Za-z0-9_]*)="
+    r"((?:'[^']*'|\"[^\"]*\"|[^\s;&|)'\"])*)")
+SHELL_VAR = re.compile(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))")
 WRITE_PATH = ("file_path", "filePath", "path", "notebook_path")
 # The write-tool name a shell write's target is handed to `capture` under. capture
 # takes a write tool's own path field and no shell tool name, and the row it
@@ -948,8 +980,107 @@ def write_paths(inp):
     paths = [m.group(1) for m in PATCH_FILE.finditer(str(inp.get("patch") or ""))]
     if paths:
         return paths
-    target = shell_target(inp.get("command") or inp.get("cmd") or "")
-    return [os.path.expanduser(os.path.expandvars(target))] if target else []
+    command = str(inp.get("command") or inp.get("cmd") or "")
+    target = shell_target(command)
+    return [os.path.expanduser(_expand(target, command))] if target else []
+
+
+def _expand(target, command):
+    """`target` with each `$VAR`/`${VAR}` the shell would substitute: an
+    assignment earlier on the same line (`B=/tmp/x; git diff > $B/f`), else the
+    environment. A name with no known value stays as spelled, so
+    `unnamed_target` can tell the gate it does not know the file. ponytail: the
+    assignments are read off the raw text, so `echo "a B=x"` counts as one; that
+    only matters when the target then reads `$B`."""
+    env = dict(os.environ)
+
+    def sub(text):
+        return SHELL_VAR.sub(
+            lambda m: env.get(m.group(1) or m.group(2), m.group(0)), text)
+
+    cut = command.find(target)
+    for m in SHELL_ASSIGN.finditer(command[:cut if cut >= 0 else len(command)]):
+        name, value = m.group(1), m.group(2)
+        if "$(" in value or "`" in value:
+            env.pop(name, None)         # a command's output: unknown here
+        elif value[:1] == "'":
+            env[name] = value.strip("'")
+        else:
+            env[name] = sub(value.strip('"'))
+    return sub(target)
+
+
+def unnamed_target(path, inp, top=None):
+    """True when a write target is no file the task rule can place in the
+    checkout: a URI (a host tool device such as `xd://<tool>`, an agent message,
+    a `conflict://N` resolution) or a shell target whose variable has no known
+    value and that `known_tail` cannot place. Refusing either names a path
+    that does not exist. A write tool's own path is never read for `$`:
+    `Outer$Inner.java` is a real file name."""
+    if URI_TARGET.match(path):
+        return True
+    if not isinstance(inp, dict):
+        return False
+    command = str(inp.get("command") or inp.get("cmd") or "")
+    return bool(command) and bool(UNEXPANDED.search(path)) and not known_tail(
+        path, top, command)
+
+
+# A value that is the checkout itself: `R=$(git rev-parse --show-toplevel)`,
+# `R=$(pwd)`, `R=$PWD`.
+ROOT_VALUE = re.compile(
+    r"^[\"']?(?:\$\(\s*(?:git\s+rev-parse\s+--show-toplevel|pwd)\s*\)"
+    r"|`\s*(?:git\s+rev-parse\s+--show-toplevel|pwd)\s*`|\$\{?PWD\}?)[\"']?$")
+
+
+def known_tail(path, top, command=""):
+    """The checkout path a target names when it opens on a variable the same
+    command line set to the checkout (`ROOT_VALUE`), or None. `R=$(git
+    rev-parse --show-toplevel); printf x > $R/src/a.py` writes `src/a.py`, so the
+    rule holds that file. Any other unknown variable - a `mktemp -d` directory,
+    a loop variable, one an earlier call exported - leaves the target unnamed:
+    re-rooting `$D/README.md` or `packages/$p/x` at the checkout refused writes
+    that never touched it (review of plan 083, N1).
+    ponytail: a root exported by an earlier call (`export R=$PWD`, then `> $R/x`)
+    is not seen, so that write passes unnamed."""
+    if not top:
+        return None
+    pieces = list(UNEXPANDED_PIECE.finditer(path))
+    if len(pieces) != 1 or pieces[0].start() != 0:
+        return None
+    name = pieces[0].group(0).strip("${}")
+    rest = path[pieces[0].end():].lstrip("/")
+    if not rest or UNEXPANDED.search(rest):
+        return None
+    cut = command.find(path)
+    head = command[:cut if cut >= 0 else len(command)]
+    values = re.findall(r"(?:^|(?<=[\s;&|(]))%s=(\$\([^)]*\)|`[^`]*`|\"[^\"]*\"|\S+)"
+                        % re.escape(name), head)
+    return (os.path.join(top, rest)
+            if values and ROOT_VALUE.match(values[-1]) else None)
+
+
+# The front matter key that makes a plan the active task (tezgah_task.active).
+PLAN_PHASE_LINE = re.compile(r"(?m)^\s*\+?\s*phase\s*:\s*\S")
+
+
+def workspace_free(rel, inp):
+    """True when `rel` is tezgah's own workspace the plan does not scope: every
+    `.tezgah/` path but the slice journal (`tezgah-task slice` writes it) and a
+    plan file that could make itself the active task - a shell write into
+    `.tezgah/plans/open/` (its text is unknown) or a write tool's text that
+    carries a `phase:` line. plan-add's own plan file and README stay free.
+    Compared casefolded: on a case-insensitive disk `.tezgah/PLANS/` is the
+    plans directory (review of plan 083, N2 and N5)."""
+    low = (rel or "").casefold()
+    if not low.startswith(".tezgah/") or low.startswith(".tezgah/slices/"):
+        return False
+    if low.startswith(".tezgah/plans/open/"):
+        if not isinstance(inp, dict) or inp.get("command") or inp.get("cmd"):
+            return False
+        return not any(isinstance(inp.get(k), str) and PLAN_PHASE_LINE.search(inp[k])
+                       for k in EDIT_TEXT)
+    return True
 
 
 def race_reason(inp, session_id, cwd=None):
@@ -970,15 +1101,239 @@ def race_reason(inp, session_id, cwd=None):
         # this guard read the scheme as a relative path. Only the harness's own
         # channels are skipped - a `file://`, `s3://` or editor URI can name a
         # real target two sessions both write, and stays guarded.
-        if URI_CHANNEL.match(path) or scratch_target(path, cwd):
+        # a shell target whose `$VAR` has no known value names no file the
+        # ledger could hold either (unnamed_target)
+        if (URI_CHANNEL.match(path) or scratch_target(path, cwd)
+                or (not URI_TARGET.match(path) and unnamed_target(path, inp))):
             continue    # a temp file or a device is no one's shared work
-        others = writers_elsewhere(path, session_id, RACE_WINDOW_MIN, cwd=cwd)
+        others = [w for w in writers_elsewhere(path, session_id, RACE_WINDOW_MIN,
+                                               cwd=cwd, lineage=True)
+                  if not ended_child(w, session_id, path, cwd)]
         if others:
-            return RACE_DENY % (", ".join(str(s) for s in others[:3]),
+            return RACE_DENY % (", ".join(race_who(*w[:3]) for w in others[:3]),
                                 RACE_WINDOW_MIN, path)
     return None
 
 
+def race_who(stem, relation, agent):
+    """One writer as RACE_DENY names it (RACE_WHO)."""
+    text = RACE_WHO.get(relation, RACE_WHO["unrelated"])
+    return text % ((agent or "?", stem) if text.count("%s") == 2 else (stem,))
+
+
+def ended_child(writer, session_id, path, cwd):
+    """True when `writer` (a writers_elsewhere (stem, relation, agent, ts)) is
+    this session's own subagent whose slice record closed after its newest
+    write of this file: a parent taking over a child that stopped on a quota
+    error is no race (research orchestrator-flow-audit S7, finding 3). The
+    record is read after `pending` closes an ended omp child, from cwd's journal
+    and the written file's. No record, one still open, or a write newer than the
+    record's close is a live writer and stays refused. ponytail: the close time
+    is stored to the second, so a write in the second the record closed counts
+    as before the close."""
+    import calendar
+    stem, relation, agent, wrote = writer
+    if relation != "child" or not agent or tezgah_task is None:
+        return False
+    repos = {r for r in (tezgah_task.main_repo(os.path.join(cwd or os.getcwd(), path)),
+                         tezgah_task.main_repo(cwd or os.getcwd())) if r}
+    base = re.sub(r"-\d+$", "", agent)
+    recs = []
+    try:
+        for repo in repos:
+            tezgah_task.pending(repo)   # closes an omp child whose transcript ended
+            recs += [r for r in tezgah_task.slices(repo) if r.get("parent") == session_id
+                     and (r.get("name") or r.get("id")) in (agent, base)]
+        closed = max(calendar.timegm(time.strptime(str(r.get("updated")), "%Y-%m-%dT%H:%M:%SZ"))
+                     for r in recs) if recs else None
+    except Exception:
+        return False
+    return (closed is not None and closed >= int(wrote)
+            and all(r.get("status") != "open" for r in recs))
+
+
+# --- lease: a sibling slice owns this file (plan 086, S6) --------------------
+# What this closes: the race rule refuses only after the other slice wrote, and
+# 24 genuine sibling refusals in real transcripts were all in a shared place -
+# one worktree for 4 or 10 concurrent slices, a predecessor's tree, a shared
+# plan record (research orchestrator-flow-audit S6, findings 3 and 5). A brief's
+# `Owns:` line is a lease on the slice record (`tezgah_task.owned_globs`), and a
+# write by one slice into a path an open sibling of the same parent owns is
+# refused before any work is lost. The second refusal is the checkout itself:
+# a slice whose record names a worktree writing into the main checkout (plan
+# 086 wave 1: two slices did, by relative paths that resolved against the
+# parent's cwd). Refused, not noted: a notice arrives after the file landed in
+# the parent's tree, and the fix - the same write under the worktree - costs
+# one re-issue. `.tezgah/` (the plan record, research data) and scratch stay
+# free: they live in the main checkout by design.
+#
+# The writing session is mapped to its record two ways. omp: its ledger's
+# `spawned` row (`tezgah_integrity.spawn_of`: parent session and spawned name);
+# omp writes it for every task child, and the record stays open while the child
+# runs. Claude: a background child's calls carry the parent's session id and
+# their own `agent_id`, which the spawn's result named and the record keeps as
+# `child` (`hooks/projects-posttooluse.py`). Every other case fails open:
+# Claude's foreground agents, dsh, Cursor and opencode open the record only when
+# the synchronous spawn returns, so no sibling record is open while the child
+# writes, and Codex writes no `spawned` row. A slice may write a path its own
+# `Owns:` names even when a sibling's names it too: the overlap is the parent's
+# brief, and the race rule still stands between the two.
+LEASE_DENY = (
+    "Lease: %s is owned by sibling slice %s (owns %s), still open under your "
+    "parent. Leave the file to it: %s, or ask your parent to move the lease; "
+    "once the owner has finished, `tezgah-task slice done %s` frees it. Every "
+    "lease is on `tezgah-task slice board`.")
+MAIN_CHECKOUT_DENY = (
+    "Lease: %s is in the main checkout %s, but your slice %s works in worktree "
+    "%s. Write the same path under that worktree: an absolute path, or a shell "
+    "whose `cwd` or `cd` is there - a relative path resolves against this "
+    "session's cwd.")
+
+
+def _channel(rec):
+    """How a sibling reaches the slice `rec` on its host."""
+    if rec.get("host") == "claude" and rec.get("child"):
+        return "message the owner (`SendMessage` to %s)" % rec["child"]
+    if rec.get("host") == "omp":
+        return "message the owner (`write agent://%s`)" % (rec.get("name") or rec["id"])
+    return "ask the owner through your parent"
+
+
+def _shell_dir(inp, cwd):
+    """The directory a shell call's redirect or `tee` target resolves against:
+    the call's own `cwd`/`workdir`, then each `cd`/`pushd` before the first
+    redirect or `tee` that writes a file, read the way `shell_control` walks
+    the line. A redirect to `/dev/*`, a descriptor (`2>&1`) or `-` writes no
+    file, so `pushd /wt >/dev/null && x > out` resolves `out` under `/wt`."""
+    base = inp.get("cwd") or inp.get("workdir")
+    where, words, pending = _full(base, cwd) if base else cwd, [], False
+    for word, is_op in _shell_words(inp.get("command") or inp.get("cmd") or ""):
+        if pending:
+            pending = False
+            if not is_op:
+                target = _unquote(word)
+                if not (target.startswith(("&", "/dev/")) or target.isdigit()
+                        or target == "-"):
+                    return where
+                continue
+        if is_op and ">" in word:
+            if words and words[-1].isdigit():
+                words.pop()  # the descriptor before `2>`
+            pending = True
+            continue
+        if not is_op:
+            if _unquote(word) == "tee" and not words:
+                return where
+            words.append(_unquote(word))
+            continue
+        while words and words[0] in SHELL_KEYWORDS:
+            words = words[1:]
+        if words and words[0] in ("cd", "pushd"):
+            dest = [a for a in words[1:] if not a.startswith("-")]
+            where = _full(dest[0] if dest else "~", where)
+        words = []
+    return where
+
+
+def lease_reason(inp, session_id, cwd=None, agent=None):
+    """LEASE_DENY or MAIN_CHECKOUT_DENY for the first of this call's files
+    that meets one, else None. `agent` is Claude's `agent_id`. Fails open: no
+    `spawned` row and no `agent_id`, no open record of that slice, an
+    unreadable journal."""
+    if spawn_of is None or tezgah_task is None or not session_id:
+        return None
+    spawn = spawn_of(session_id) or ((session_id, agent) if agent else None)
+    if not spawn:
+        return None
+    here = cwd or os.getcwd()
+    try:
+        if inp.get("command") or inp.get("cmd"):
+            here = _shell_dir(inp, here)
+        for path in write_paths(inp):
+            if (URI_CHANNEL.match(path) or scratch_target(path, here)
+                    or unnamed_target(path, inp)):
+                continue
+            real = os.path.realpath(os.path.join(here, os.path.expanduser(path)))
+            repo = tezgah_task.main_repo(real)
+            me = tezgah_task.slice_of(repo, *spawn) if repo else None
+            if not me or me.get("status") != "open":
+                continue
+            tree = me.get("declared") or ""
+            top = linked_main(real) and tezgah_task._sibling_worktree(real, repo)
+            rel = os.path.relpath(real, top or repo).replace(os.sep, "/")
+            if rel.startswith((".tezgah/", "../")) or rel == ".tezgah":
+                continue
+            if not top and tree and tree != repo and os.path.isdir(tree):
+                return MAIN_CHECKOUT_DENY % (rel, repo, me["id"], tree)
+            if any(tezgah_task.match(rel, g) for g in me.get("owns") or ()):
+                continue
+            owner = tezgah_task.owner_of(repo, rel, spawn[0], me["id"])
+            if owner:
+                return LEASE_DENY % (rel, owner.get("name") or owner["id"],
+                                     ", ".join(owner["owns"][:3]), _channel(owner),
+                                     owner["id"])
+    except Exception:
+        return None
+    return None
+
+
+def spawn_advice(tool, inp, session_id, cwd=None):
+    """The shared-worktree warning for a spawn call (`tezgah_task.worktree_clash`),
+    else None. A warning, never a deny: a fan-out of read-only reviewers on one
+    checkout is fine, and the agent name is how this reads which ones are. Off
+    under `orchestrate-off`, whose rule text it backs."""
+    if (str(tool or "").lower() not in SUBAGENT_TOOLS or tezgah_task is None
+            or not cwd or off("orchestrate-off")):
+        return None
+    try:
+        root = tezgah_task.main_repo(cwd)
+        return tezgah_task.worktree_clash(root, tool, inp, session_id or "") if root else None
+    except Exception:
+        return None
+
+
+# The cross-project write notice: a session works under the rules of the
+# repository its cwd is in, so a write into another one is under none of that
+# repository's plans, lessons or slice journal (research orchestrator-flow-audit
+# S7, finding 7). A notice, never a refusal: the write may be the user's ask.
+CROSS_PROJECT = (
+    "tezgah: this write is in %s, not in this session's repository (%s). That "
+    "repository's plans, lessons and slice journal do not apply to this session. "
+    "Work on that project from a session opened there.")
+
+
+def _main_repo(path):
+    """The main checkout of the repository holding `path`, else None
+    (`tezgah_task.main_repo`: a repository's own `.tezgah` is that repository)."""
+    return tezgah_task.main_repo(path) if tezgah_task is not None else None
+
+
+def cross_project_note(session_id, tool, inp, cwd):
+    """CROSS_PROJECT when this write call's file lies in another repository than
+    cwd's (a worktree counts as its main checkout), once per session per target
+    repository (a `nudged` mark), else None. Every host's post-tool channel
+    carries it beside its other notices. Total: any failure is no notice."""
+    try:
+        name = str(tool or "").lower()
+        if (name not in WRITE_TOOLS and name not in BASH_TOOLS) or not cwd \
+                or not isinstance(inp, dict) or inp.get("command") == "view":
+            return None
+        here = _main_repo(cwd)
+        for path in write_paths(inp):
+            if URI_CHANNEL.match(path) or scratch_target(path, cwd):
+                continue
+            there = _main_repo(os.path.join(cwd, path))
+            if not there or there == here:
+                continue
+            key = "cross:" + hashlib.sha1(("%s\0%s" % (session_id, there)).encode(
+                "utf-8", "replace")).hexdigest()[:16]
+            return CROSS_PROJECT % (there, here or cwd) \
+                if tezgah_store.mark("nudged", key) else None
+    except Exception:
+        return None
+    return None
+
+
 # --- task scope: the plan's own phase and path allowlist --------------------
 # What this closes: a session that has declared what it is working on - a plan
 # file under .tezgah/plans/open is active, so the work has a phase and the
@@ -1013,13 +1368,19 @@ TASK_PHASE_DENY = (
     "the plan's Acceptance, spike and checkpoint are in order.")
 TASK_SCOPE_DENY = (
     "Task gate: %s is outside the paths the active task %s allows (%s). If the "
-    "plan's work genuinely reaches it, widen the scope yourself with `tezgah-task "
-    "allow <glob> ... --why \"<reason>\"` (listing the current globs too); "
-    "otherwise leave the file alone.")
+    "plan's work genuinely reaches it, widen the scope yourself (allow replaces "
+    "the list, so this keeps the current globs): `%s --why \"<what in the plan "
+    "reaches it>\"`; otherwise leave the file alone.")
+# a target outside the repository: an allow glob is repo-relative, so none reaches it
+TASK_SCOPE_OUTSIDE = (
+    "Task gate: %s is outside the paths the active task %s allows (%s). It lies "
+    "outside this repository, and an allow glob is relative to it, so no "
+    "`tezgah-task allow` line reaches it; leave the file alone, or do the work "
+    "under that repository's own task.")
 TASK_RECORD_DENY = (
-    "Task gate: %s is the active task's own record. The phase and the allowlist "
-    "live in that file and only `tezgah-task` writes them, because it checks the "
-    "plan's Acceptance, spike and review on the way; change the task through it.")
+    "Task gate: %s is the active task's own record; only `tezgah-task` writes it, checking the plan's "
+    "Acceptance, spike and review on the way. The phase and allowlist: `tezgah-task phase|allow`; an "
+    "Acceptance box: `tezgah-task tick NNN <n>`; State/Next: `tezgah-task note NNN state|next \"...\"`.")
 # The shapes that make a shell command a write, for the phase rule below. The
 # tools are not the only way to change a file, and E7b measured the other one:
 # with `edit` and `write` refused twelve and six times, the armed arm wrote the
@@ -1127,18 +1488,42 @@ def task_reason(inp, cwd, base, task=_UNRESOLVED):
     task = _task(cwd, base, task)
     if not task:
         return None
+    # The targets the plan scopes: not a URI or a shell target with no known
+    # value (unnamed_target), and not tezgah's own gitignored workspace under
+    # `.tezgah/` (research lines, lessons, briefs) - the active record there is
+    # task_record_reason's, refused before this rule runs. A call whose every
+    # target is one of those writes no project file, so the phase does not
+    # refuse it either; a call with no target at all still meets the phase.
+    paths = write_paths(inp)
+    project = []
+    top = tezgah_task.repo_root(cwd, base) if cwd else None
+    command = str(inp.get("command") or inp.get("cmd") or "") if isinstance(inp, dict) else ""
+    for spelled in paths:
+        if unnamed_target(spelled, inp, top):
+            continue
+        path = (known_tail(spelled, top, command) or spelled) if command else spelled
+        rel = tezgah_task.relative(path, cwd, base, worktrees=True)
+        if rel is not None and workspace_free(rel, inp):
+            continue
+        project.append((spelled, path, rel))
+    if paths and not project:
+        return None
     if task["phase"] not in tezgah_task.WRITE_PHASES:
         return TASK_PHASE_DENY % (task["id"], task["phase"],
                                   " or ".join(tezgah_task.WRITE_PHASES))
     patterns = task["allowed_paths"]
     if not patterns:
         return None
-    for path in write_paths(inp):
-        if scratch_target(path, cwd):
+    for spelled, path, rel in project:
+        if scratch_target(spelled, cwd):
             continue
-        rel = tezgah_task.relative(path, cwd, base)
         if rel is None or not any(tezgah_task.match(rel, p) for p in patterns):
-            return TASK_SCOPE_DENY % (path, task["id"], ", ".join(patterns))
+            # the call's own spelling: the agent has to recognize its argument
+            if rel is None:
+                return TASK_SCOPE_OUTSIDE % (spelled, task["id"], ", ".join(patterns))
+            ready = " ".join(["tezgah-task allow"] + [shlex.quote(p) for p in
+                                                      list(patterns) + [rel]])
+            return TASK_SCOPE_DENY % (spelled, task["id"], ", ".join(patterns), ready)
     return None
 
 
@@ -1203,6 +1588,9 @@ def checkpoint_reason(inp, cwd, base, task=_UNRESOLVED):
         # a shell line that changes no file is not this rule's, the same read of
         # the same shape table task_shell_reason makes
         return None
+    paths = write_paths(inp)
+    if command is None and paths and all(URI_TARGET.match(p) for p in paths):
+        return None     # a tool device or a message changes no tree state
     task = _task(cwd, base, task)
     if not task or task["phase"] != "implementation":
         return None
@@ -1276,6 +1664,18 @@ def workspace_reason(inp, cwd, base):
 # or whose target is a positional argument (`cp`, `sed -i`), leaves a row with
 # no `key` or no row at all - the gate cannot read the line it adds - so the
 # context cannot label that line.
+#
+# History, whatever the turn read (plan 077, rsi-borrow-screen idea 2): a write
+# that rewrites or removes a ledger line leaves one `lesson_changed` row per such
+# line, keyed by the old line and carrying its text, so a standing constraint
+# that was edited away can be read back from the ledger. Still never a refusal.
+# ponytail: a shell write the gate cannot read the new text of (`sed -i`, an
+# `echo >` body) leaves no `lesson_changed` row, and a rewritten line carries no
+# `new_key`: the row contract (`tezgah_integrity.LEDGER_FIELDS`) has no field
+# for it, so the line's new key rides only its `lesson_tainted` row, if any.
+LESSON_CHANGED_MAX = 10
+
+
 def lesson_taint(tool, inp, cwd, session_id, agent=None, shell_body=None):
     """Write one `lesson_tainted` row per lesson line this call leaves in a
     ledger that the ledger did not hold, when the user turn already holds a row
@@ -1285,24 +1685,28 @@ def lesson_taint(tool, inp, cwd, session_id, agent=None, shell_body=None):
     the call lands (`_after_text`), so a partial-line edit names the line it
     leaves, not its fragment. The keyed rows also go to the ledger's repository
     index (`tezgah_lessons.write_taint`), which the context labels lines from.
+    In any turn, one `lesson_changed` row per ledger line the call drops - its
+    old `key`, its old text in `detail` (redacted by `note`), the ledger in
+    `target`: read off the post-write text, a patch's `-` lines, or a shell
+    heredoc that overwrites the file; an append drops nothing.
     Returns nothing: it is never a refusal."""
-    if tezgah_lessons is None or turn_rows is None or not session_id:
+    if tezgah_lessons is None or not session_id:
         return
     t = str(tool or "").lower()
 
     def norm(path):
         return os.path.normpath(os.path.join(cwd, os.path.expanduser(path)))
 
-    texts = {norm(path): new for path, _old, new in
-             write_texts(inp if t in WRITE_TOOLS else shell_body)}
+    written = write_texts(inp if t in WRITE_TOOLS else shell_body)
+    texts = {norm(path): new for path, _old, new in written}
     targets = sorted(p for p in set(texts) | set(map(norm, write_paths(inp)))
                      if tezgah_lessons.is_ledger(p))
     if not targets:
         return
     source = next((row["source"] for row in reversed(
-        turn_rows(session_id, agent=agent)) if row.get("source")), None)
-    if not source:
-        return
+        turn_rows(session_id, agent=agent)) if row.get("source")),
+        None) if turn_rows else None
+    minus = {norm(path): old for path, old, _new in written}
     key_of = tezgah_lessons.lesson_key
     for path in targets:
         try:
@@ -1310,23 +1714,68 @@ def lesson_taint(tool, inp, cwd, session_id, agent=None, shell_body=None):
                 current = fh.read()
         except OSError:
             current = ""
-        have = set(map(key_of, tezgah_lessons.entries(current)))
+        lines = tezgah_lessons.entries(current)
+        have = set(map(key_of, lines))
         new = texts.get(path)
+        gone = ()
         if t in WRITE_TOOLS and new is not None:
             after = _after_text(inp, current)
-            new = new if after is None else after    # None: a patch's `+` lines
+            if after is None and path in _patch_deletes(inp, norm):
+                gone = list(dict.fromkeys(lines))    # a patch's Delete File
+            elif after is None:  # a patch: its `-` lines leave, its `+` lines land
+                gone = _dropped(tezgah_lessons.entries(minus.get(path) or ""), new)
+            else:
+                new, gone = after, _dropped(lines, after)
+        elif new is not None and not _shell_appends(inp.get("command")):
+            gone = _dropped(lines, new)
+        fields = dict(target=path, agent=agent, workspace=root_for(cwd),
+                      id=call_id(tool, inp))
+        # a rewrite of the whole ledger would otherwise push the refusal rules'
+        # fixed tails (the last verify, prior calls) out of their window
+        for line in gone[:LESSON_CHANGED_MAX]:
+            note(session_id, "lesson_changed", line, key=key_of(line), **fields)
+        if len(gone) > LESSON_CHANGED_MAX:
+            rest = len(gone) - LESSON_CHANGED_MAX
+            note(session_id, "lesson_changed", "%d more lines changed" % rest,
+                 items=rest, **fields)
+        if not source:
+            continue
         keys = [k for k in dict.fromkeys(map(key_of, tezgah_lessons.entries(
             new or ""))) if k not in have] or [None]
-        fields = dict(source=source, target=path, agent=agent,
-                      workspace=root_for(cwd), id=call_id(tool, inp))
         for key in keys:
-            note(session_id, "lesson_tainted", source, key=key, **fields)
+            note(session_id, "lesson_tainted", source, key=key, source=source,
+                 **fields)
         if keys != [None]:
             write_taint(os.path.dirname(os.path.dirname(path)), have | set(keys),
                         [{"key": k, "source": source, "ts": int(time.time())}
                          for k in keys])
 
 
+PATCH_DELETE = re.compile(r"^\*\*\* Delete File: (.+?)\s*$", re.M)
+
+
+def _patch_deletes(inp, norm):
+    """The paths an apply_patch input deletes (`*** Delete File: <path>`), normed;
+    read from the patch text itself, so a hunk of blank lines is not a delete."""
+    text = "\n".join(v for v in (inp or {}).values() if isinstance(v, str))
+    return {norm(p) for p in PATCH_DELETE.findall(text)}
+
+
+def _dropped(lines, after):
+    """The ledger `lines` the text `after` no longer holds, once each, in order."""
+    keep = set(map(tezgah_lessons.lesson_key, tezgah_lessons.entries(after)))
+    return [ln for ln in dict.fromkeys(lines)
+            if tezgah_lessons.lesson_key(ln) not in keep]
+
+
+def _shell_appends(command):
+    """Whether a shell write's body is added to its target (`>>`, `tee -a`) rather
+    than replacing it; True when the target is not read (no row beats a false one)."""
+    m = SHELL_TARGET.search(mask(str(command or "")))
+    return not m or m.group(0).startswith(">>") or bool(
+        re.search(r"\s-(?:[A-Za-z]*a[A-Za-z]*|-append)\s", m.group(0)))
+
+
 # --- the shell's write body: three write-tool rules reached through a heredoc -
 # What this closes (the route E7c measured): SKIP_TEST, ATTRIB_LINE and the
 # prefixed-token credential scan (secret_edit) read the text a write tool lands,
@@ -1570,6 +2019,48 @@ def effectful(tool, inp):
     return mcp_class(tool) is not None
 
 
+# --- ready: an idle `wait` while ready steps are open (plan 086, S1) ----------
+# omp's `wait` blocks the parent until a job settles. Measured over 15 omp
+# sessions, 68.3% of spawns were followed by `wait` with no other call between,
+# and at 86 of the 163 such waits that had a todo list two or more items were
+# open. The owner's default is a warning, never a deny: the line rides back with
+# the wait's result, as the graph line does (`graph_advice`).
+READY_WAIT = (
+    "tezgah: idle wait - nothing ran since the spawn while %d ready todo "
+    "step(s) are open: %s. Dispatch every ready step now, independent ones as "
+    "subagents in one message, or mark it blocked on the slice it waits for. "
+    "Ending the turn is the non-blocking alternative to `wait`: the host wakes "
+    "you on the result.")
+
+
+def ready_advice(tool, session_id, cwd=None):
+    """The idle-wait warning for a `wait` call, else None: the newest spawn in
+    the ledger tail is followed by no call but waits and todo updates, and the
+    session's newest `todo` row (`tezgah_integrity.newest_todo`) holds a ready
+    item no open slice of this session is working on
+    (`tezgah_integrity.ready_heads`). A row with no `tool` (a turn marker, a
+    `spawn` row) is no call. Off under `orchestrate-off`, whose rule text it
+    backs."""
+    if str(tool or "").lower() != "wait" or not session_id:
+        return None
+    if off("orchestrate-off"):
+        return None
+    rows = events(session_id, tail=DRIFT_TAIL)
+    for row in reversed(rows):
+        name = str(row.get("tool") or "").lower()
+        if name in SUBAGENT_TOOLS:
+            break
+        if name and name != "wait" and name not in TODO_TOOLS:
+            return None
+    else:
+        return None
+    todo = newest_todo(reversed(rows))
+    heads = ready_heads(todo, session_id, cwd) if todo else []
+    if not heads:
+        return None
+    return READY_WAIT % (len(heads), "; ".join(cut(h, 48) for h in heads[:3]))
+
+
 # --- plan required: work that spans files on main has no plan ----------------
 # What this closes: a turn that wrote four product files - a hook, its tests, its
 # docs and the changelog - straight onto `main`, with the plan opened afterwards.
@@ -2642,6 +3133,16 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
         reason = race_reason(inp, session_id, cwd)
         if reason:
             return _deny(session_id, "race", reason, tool, inp, base)
+    # Lease: a write into a file an open sibling slice owns, or into the main
+    # checkout by a slice whose record names a worktree (see LEASE_DENY). After
+    # the race rule, which names a write already lost; before the task scope,
+    # since the allowlist is the plan's and the lease is one slice's share of it.
+    # It backs the fan-out rule's text, so its switch is that rule's; with the
+    # journal off there is no record to read.
+    if writes and not off("orchestrate-off") and not off("slices-off"):
+        reason = lease_reason(inp, session_id, cwd, agent)
+        if reason:
+            return _deny(session_id, "lease", reason, tool, inp, base)
     # Task scope: the active plan's phase and the files its allowlist names (see
     # task_reason). The record itself is refused first of all: only
     # bin/tezgah-task writes it, through the checks it makes on the way.
@@ -2805,8 +3306,9 @@ def _dry_decision(tool, inp, cwd, session_id, agent=None):
     """`decision` with every write it makes swapped out for the call.
 
     The writers are module names `decision` reaches through (`note` for the
-    deny, drift, nudge and lesson_tainted rows, `write_taint` for the lesson
-    taint index, `first_nudge` for the once-per-session mark, `capture` for the
+    deny, drift, nudge, lesson_tainted and lesson_changed rows, `write_taint`
+    for the lesson taint index, `first_nudge` for the once-per-session mark,
+    `capture` for the
     snapshot), so one swap covers every rule and a new rule
     that records through them is dry here without being told. Safe because
     the dry run is its own process (bin/tezgah-gate check): nothing else in it
@@ -2836,6 +3338,54 @@ def _dry_decision(tool, inp, cwd, session_id, agent=None):
 DENY_RULES = {"control": None, "explorer": None, "shortcut": "verify-off",
               "piped": "verify-off",
               "attribution": None, "lang": "lang-off", "race": None,
+              "lease": "orchestrate-off",
               "task": "task-off", "workspace": "workspace-off", "secret": None,
               "plan": None, "order": "verify-off", "loop": "verify-off",
               "retry": "verify-off", "drift": "reminder-off"}
+
+
+# --- ask: an ask-tool question with no recommended option (plan 086, S3) -----
+# The ask policy's structured half: omp's `ask` and Claude's AskUserQuestion
+# carry their questions as data, so the check needs no word list for the
+# question itself. 7 of 51 distinct `ask` questions in the owner's omp
+# transcripts carried no `recommended` option (research orchestrator-flow-audit
+# S3, finding 4). A warning, never a deny (the owner's 2026-09-26 decision
+# removed the per-command consent gate): the line rides back with the call's
+# result, as the graph line does (`graph_advice`). Every such call leaves an
+# `ask` row, the counts `tezgah-gate replay` and the ledger read.
+ASK_NO_DEFAULT = (
+    "tezgah: %d of %d question(s) in this %s call carry no "
+    "recommended option. Each question put to the user names a recommended "
+    "default (omp `ask`: `recommended`; AskUserQuestion: a \"({RECOMMENDED})\" "
+    "option), and the work proceeds on it unless the step waits on the user's "
+    "answer by nature (a force push, a delete of what the session did not "
+    "make, production, a credential, a spend over the cap). ")
+ASK_GRANTED = (
+    "tezgah: the user already granted %s this session; that step is taken, "
+    "not asked again.")
+
+
+def ask_advice(tool, inp, session_id, cwd=None):
+    """The ask-policy warning for an ask-tool call, else None: a question with
+    no recommended option (`tezgah_integrity.undefaulted`), or one about an
+    outward step the user granted this session (`grants_in_force`). Records
+    one `ask` row per call with the counts. Off under `verify-off`, whose Stop
+    rule the policy's other half rides, and `pretooluse-off`."""
+    from tezgah_integrity import (ASK_TOOLS, _said as said, grants_in_force,
+                                  never_default, outward_classes, undefaulted)
+    name = str(tool or "").lower()
+    if name not in ASK_TOOLS or not session_id or not (cwd and root_for(cwd)) \
+            or off("pretooluse-off") or off("verify-off"):
+        return None
+    asked, defaulted = undefaulted(inp)
+    if not asked:
+        return None
+    qs = inp.get("questions") if isinstance(inp.get("questions"), list) else [inp]
+    text = " ".join(str(q.get("question") or "") for q in qs if isinstance(q, dict))
+    note(session_id, "ask", cut(" ".join(text.split()), 120), tool=str(tool),
+         questions=asked, defaults=defaulted)
+    out = ASK_NO_DEFAULT % (asked - defaulted, asked, tool) if defaulted < asked else ""
+    granted = outward_classes(text) & grants_in_force(session_id)
+    if granted and not never_default(text):
+        out += ASK_GRANTED % ", ".join(sorted(granted))
+    return said(out.strip()) if out else None