@kaydash9999/banker-plugins 0.14.0 → 0.15.1

package/skills/lineage/lineage.py

@@ -18,6 +18,7 @@ import os
 import pathlib
 import re
 import sys
+import tempfile
 from html.parser import HTMLParser
 
 if sys.version_info < (3, 7):
@@ -32,6 +33,16 @@ ECHO_ASK = 40               # echo-exchange: user question length ceiling (A-4)
 ECHO_REPLY = 5              # echo-exchange: assistant reply length ceiling (A-4)
 _BLOCKQUOTE_MAX_DEPTH = 32  # blockquote recursion cap (C-2)
 CACHE_BASE = pathlib.Path.home() / ".cache" / "lineage"
+REVIEW_SCHEMA = "lineage-review/1"       # --emit-review pack, read back by --apply-review
+REVIEW_PART_SCHEMA = "lineage-review-part/1"
+REVIEW_PART = 40            # turns per part file: one reviewer's share
+PREVIEW_HEAD = 1500         # a long turn's preview: head + tail, where conclusions sit
+PREVIEW_TAIL = 700
+SUMMARY_MAX = 120           # a reviewer's summary is cut to this, after redaction
+LLM_CACHE_VERSION = 1       # bump to drop every cached reviewer decision
+REVIEWER_TIMEOUT = 60       # --reviewer-timeout default, seconds
+DECISIONS_MAX = 1_000_000   # bytes in one decisions file (a 40-turn part answers in some 20 KB)
+DECISIONS_TRIES = 200       # places a wrapped answer's list may start, tried at most
 
 # ---------------------------------------------------------------- Noise / classify
 # NOTE: JSONL records carry RAW `<...>` tags. Every regex below uses raw `<`/`>`
@@ -155,7 +166,7 @@ def _mask(s: str) -> str:
     return (s[:4] + "****" + s[-4:]) if len(s) > 8 else "[REDACTED]"
 
 
-def redact(text: str, extra: str = None, mode: str = "full"):
+def redact(text: str, extra: "str | None" = None, mode: str = "full"):
     """Multi-layer redaction. Returns (redacted_text, count_by_kind)."""
     counts = {}
     out = text
@@ -218,6 +229,72 @@ def redact(text: str, extra: str = None, mode: str = "full"):
     return out, counts
 
 
+# A character of curl's user before the colon: no space, : or =, and a quote, backtick or ( only
+# where no flag follows (-u, -Xu or --user, as either branch below starts). A match starts only
+# there, so no user runs past the place where the next match may start: a long run stays linear,
+# and a user joined to a variable by a - ("$USER"-bot) is read whole.
+_CU_USER = r"(?:[^\s:=\"'`(]|[\"'`(](?!-(?:u|[A-Za-z0-9]{1,6}u[\s\"']|-user[\s=\"'])))"
+# The quotes that may open the value, bare or escaped (\" and \\\" in a quoted command, '\'' and
+# '"'"' from bash and shlex.quote, ^" in cmd, `" in PowerShell, $' in bash): up to six in a row.
+_CU_LEAD = r"(?:[\\^`$]{0,7}[\"']){0,6}"
+# Values read as a whole token, past the quotes that open them, that hold no user and password: a
+# uid:gid (docker), a date format (date -u +%H:%M), two references ($UID:$GID, ${UID}:${GID},
+# %USER%:%PASS%, $(id -u):$(id -g), whose inner `-u)` is a match of its own) and a path default
+# (mktemp -u "${TMPDIR:-/tmp}/x"). A literal password, or a default that is no path or holds a
+# colon, is hidden.
+_CU_REF = r"(?:\$\{?\w+\}?|%\w+%|\$\([^\s()]*(?:\s+[^\s()]+)*\))"
+_CU_SKIP = (r"(?!" + _CU_LEAD + r"(?:\+[\"']?%[-_0^#]?[A-Za-z%]|(?:\d+:\d+|(?:" + _CU_REF
+            + r"|[^\s:=\"'`(]*\)):" + _CU_REF + r")(?![^\s\"'`;|&)\\^])"
+            r"|\$\{\w+:[-=?+]?[/~.][^\s}\"'`(:]*\}[^\s:]*(?!\S)))")
+
+# Extra patterns for text a reviewer model reads (part files) and nothing else: the page
+# and --rulebase keep the patterns above, so their output stays as it was.
+REVIEW_SECRET_PATTERNS = [
+    ("AnthropicKey", re.compile(r"(?<![A-Za-z0-9])sk-ant-[A-Za-z0-9_-]{20,}")),
+    ("OpenAIKey", re.compile(r"(?<![A-Za-z0-9-])sk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}")),
+    ("GoogleKey", re.compile(r"(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}")),
+    # bounded repeats: a long run of `key` or `a.` would otherwise take quadratic time
+    ("HexKey", re.compile(r"(?i)(?:key|token|secret)[\w-]{0,100}\s*[:=]\s*['\"]?[0-9a-f]{32,}")),
+    ("PasswordBare", re.compile(
+        r"(?i)(?:password|passwd|passcode|pwd|암호|비번|비밀\s?번호|패스워드)\s*[:=]\s*[^\s'\"]{6,}")),
+    # the password runs to the last @ before the host: it may hold an @ of its own
+    ("UrlCredential", re.compile(r"(?i)[a-z][a-z0-9+.-]{0,30}://[^\s:@/]*:[^\s/]{3,}@")),
+    ("Bearer", re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]{16,}")),
+    # Authorization then `:`, `=`, `=>` or headers["Authorization"] =, a call's ("Authorization",
+    # "...") and a HAR name/value pair, or a space before a quote (nginx, Apache)
+    ("BasicAuth", re.compile(
+        r"(?i)\bauthorization"
+        r"(?:[\"']?\]?\s*(?:=>|[:=])"
+        r"|[\"']\s*,\s*(?:[\"']value[\"']\s*:\s*)?(?=[\"'])"
+        r"|\s+(?=[\"']))"
+        r"\s*[\"']?basic\s+[A-Za-z0-9+/]{8,}={0,2}")),
+    # curl's -u and --user flags, alone or last in a bundle (-su, -4u), with a user and password
+    # after a space, an = or nothing, quoted together or apart ("user":"pw"), with quotes bare,
+    # escaped or nested (_CU_LEAD) or none, in inline code or parentheses, or as two items of an
+    # argument list. An empty user with a token, and a
+    # long key as the user with no password, count too. The separators share no character with
+    # the user name, so a long run of them stays linear. The values _CU_SKIP names and a
+    # host:/path (rsync) are left.
+    ("CurlUser", re.compile(
+        r"(?<![^\s\"'`(])(?:-u\s*|-[A-Za-z0-9]{1,6}u\s+|--user(?:\s+|=))" + _CU_SKIP + _CU_LEAD
+        + r"(?:" + _CU_USER + r"*:(?!/)\S{3,}|" + _CU_USER + r"{15,}:(?=[\s\"'`).,;\\]|$))"
+        r"|([\"'])(?:-[A-Za-z0-9]{0,6}u|--user)\1\s*,\s*([\"'])" + _CU_SKIP
+        + r"(?:" + _CU_USER + r"*:[^\s\"']{3,}|" + _CU_USER + r"{15,}:)\2")),
+]
+
+
+def review_redact(text, extra=None):
+    """Text as a reviewer model reads it: the reviewer-only patterns first, while the keys
+    are whole (the entropy rule would otherwise cut a key and leave the rest), then fully
+    redacted (never masked, whatever --redact-mode says). Returns (text, count)."""
+    n = 0
+    for name, pat in REVIEW_SECRET_PATTERNS:
+        text, k = pat.subn(f"[REDACTED:{name}]", text)
+        n += k
+    red, found = redact(text, extra=extra, mode="full")
+    return red, n + sum(found.values())
+
+
 # ---------------------------------------------------------------- Discovery
 _TITLE_RE = re.compile(r'"customTitle"\s*:\s*"([^"]+)"')
 
@@ -372,7 +449,8 @@ def parse_turns(stream, unsafe_schema: bool = False, session_id=None,
         yield {"role": role, "text": text, "ts": ts, "uuid": uuid_,
                "tools": tools, "line_no": line_no,
                "parts": [text] if text else [],       # R1: always seed parts
-               "session": session_id, "session_name": session_name}
+               "session": session_id, "session_name": session_name,
+               "meta": bool(obj.get("isMeta"))}       # a harness-injected body
 
 
 # ---------------------------------------------------------------- Classify (A-1..A-4)
@@ -443,10 +521,10 @@ def merge_assistant_runs(turns):
     return merged
 
 
-def drop_echo_exchanges(turns):
-    """Drop no-op exchanges: a short user question + a tool-less token reply.
-    Structural, not keyword-based (A-4). Same-session only. Dropping a reply
-    also drops its question (else the question is orphaned).
+def echo_indices(turns):
+    """Indices of no-op exchanges: a short user question + a tool-less token reply.
+    Structural, not keyword-based (A-4). Same-session only. A reply's question is
+    included with it (else the question is orphaned).
     """
     drop = set()
     for i, t in enumerate(turns):
@@ -457,6 +535,12 @@ def drop_echo_exchanges(turns):
                 and len(n["text"].strip()) <= ECHO_REPLY
                 and n.get("session") == t.get("session")):
             drop |= {i, i + 1}
+    return drop
+
+
+def drop_echo_exchanges(turns):
+    """Drop the no-op exchanges echo_indices finds."""
+    drop = echo_indices(turns)
     return [t for i, t in enumerate(turns) if i not in drop]
 
 
@@ -567,23 +651,35 @@ def read_or_summarize(turn: dict, session_id: str, rebuild: bool = False,
     digest = hashlib.sha256(
         (turn["text"] + "\x00s" + str(SUMMARIZER_VERSION)).encode()
     ).hexdigest()[:8]
-    p = cache_dir(turn.get("session") or session_id) / f"{turn['uuid']}-{digest}.txt"
-    if p.exists() and not rebuild:
+    try:                                          # ids come from the transcript: keep them in the cache
+        p = (cache_dir(_safe_name(turn.get("session") or session_id))
+             / f"{_safe_name(turn['uuid'])}-{digest}.txt")
+    except OSError as e:                          # no writable cache: summarize anyway
+        _warn_once("_no_cache", f"cache unavailable ({e}); summaries are not cached")
+        p = None
+    if p is not None and p.exists() and not rebuild:
         try:
             return p.read_text(encoding="utf-8").strip(), True
         except (OSError, UnicodeDecodeError):
             pass
     raw_summary = summarize_turn(turn)
     redacted, _ = redact(raw_summary, extra=redact_extra, mode=redact_mode)
-    try:
-        fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            f.write(redacted)
-    except OSError:
-        pass
+    if p is not None:
+        try:
+            fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(redacted)
+        except OSError:
+            pass
     return redacted, False
 
 
+def _warn_once(key, message):
+    if not getattr(_warn_once, key, False):
+        print(f"[lineage] WARN: {message}", file=sys.stderr)
+        setattr(_warn_once, key, True)
+
+
 # ---------------------------------------------------------------- Markdown (C-1..C-3)
 # Carve code spans and https-only links to opaque sentinels BEFORE emphasis, so
 # no emphasis rule ever runs over emitted markup (C-2). Sentinel chars exclude
@@ -920,12 +1016,32 @@ HTML_TEMPLATE = r"""<!DOCTYPE html>
 
 
 # ---------------------------------------------------------------- Render rows
+def user_fold_summary(redacted_text):
+    """The summary line of a user turn long enough to fold (USER_FOLD)."""
+    return _cut(redacted_text.replace("\n", " "), 90)
+
+
+def _page_summary(t, summaries, session_id, rebuild, redact_extra, redact_mode):
+    """(summary, cache_hit) of a bot turn as the page shows it: the reviewer's when
+    `summaries` has one (cache_hit None: no rule summary was looked up), else the
+    rules' (cached)."""
+    if summaries is not None and t.get("uuid") in summaries:
+        return summaries[t["uuid"]], None
+    return read_or_summarize(t, session_id, rebuild=rebuild,
+                             redact_extra=redact_extra, redact_mode=redact_mode)
+
+
+def _reviewed_fold(t, summaries):
+    """A reviewer's summary for a folded user turn, or None."""
+    return summaries.get(t.get("uuid")) if summaries is not None else None
+
+
 def _fmt_time(ts):
     return ts[11:16] if ts and len(ts) >= 16 else ""
 
 
 def render_rows(turns, session_id, redact_extra, redact_mode, rebuild,
-                open_details=False, markdown=True, all_sessions=False):
+                open_details=False, markdown=True, all_sessions=False, summaries=None):
     rows = []
     last_date = None
     last_session = None
@@ -968,7 +1084,8 @@ def render_rows(turns, session_id, redact_extra, redact_mode, rebuild,
         if role == "user":
             red = _red(t["text"])
             if len(red) > USER_FOLD:
-                summary = html.escape(_cut(red.replace("\n", " "), 90))
+                reviewed = _reviewed_fold(t, summaries)
+                summary = html.escape(_red(reviewed) if reviewed else user_fold_summary(red))
                 body = render_body(red, markdown=markdown)
                 rows.append(
                     '<div class="row me"><span class="time">%s</span>'
@@ -984,12 +1101,11 @@ def render_rows(turns, session_id, redact_extra, redact_mode, rebuild,
             continue
 
         # assistant or agent bubble
-        cache_total += 1
-        summary, hit = read_or_summarize(
-            t, session_id, rebuild=rebuild,
-            redact_extra=redact_extra, redact_mode=redact_mode)
-        if hit:
-            cache_hits += 1
+        summary, hit = _page_summary(t, summaries, session_id, rebuild,
+                                     redact_extra, redact_mode)
+        if hit is not None:
+            cache_total += 1
+            cache_hits += bool(hit)
         esc_sum = html.escape(_red(summary))
         detail_body = render_body(_red(t["text"]), markdown=markdown)
 
@@ -1105,6 +1221,693 @@ def self_verify(html_text: str):
 
 
 # ---------------------------------------------------------------- CLI
+# ---------------------------------------------------------------- Review pack
+# The default /lineage flow: --emit-review packs the turns for the session's model,
+# its reviewers write keep/summary decisions, --apply-review renders from them. The
+# pack holds redacted text only. Noise the rules are certain of (wrapper blocks, hook
+# feedback, injected bodies) is gone before the pack; the rules' judgement calls (echo
+# exchanges, tool-only turns) stay in it, marked, for the reviewers to confirm or undo.
+def _is_keep(v):
+    return v is None or isinstance(v, bool)
+
+
+def _is_summary(v):
+    return v is None or isinstance(v, str)
+
+
+def _first(*values):
+    for v in values:
+        if v is not None:
+            return v
+    return None
+
+
+def _bad(message):
+    print(f"[lineage] ERROR: {message}", file=sys.stderr)
+    return None
+
+
+def _write_private(path, text):
+    """Write `text` to `path` as a fresh 0600 file, replaced whole. The temporary file
+    comes from mkstemp (created exclusively, 0600), so a link planted at a guessable name
+    is never followed, and it is removed when the write fails."""
+    path = pathlib.Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+        os.replace(tmp, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _safe_name(s):
+    """A file-name-safe form of an id read from a transcript or a pack."""
+    s = re.sub(r"[^A-Za-z0-9_.-]", "_", str(s or "default"))[:80]
+    return s if s.strip(".") else "_"
+
+
+def _decision_context(why, keeps):
+    """What a cached decision rests on beside the text: the rules' call on the turn (a
+    `keep: null` defers to it) and the keep flags the reviewer was told to honour."""
+    return "|".join([why or "", str(keeps.get("keep_trivia") is True),
+                     str(keeps.get("keep_tool_only") is True)])
+
+
+def _llm_cache_path(turn_id, session, redacted_text, context):
+    digest = hashlib.sha256((redacted_text + "\x00llm" + str(LLM_CACHE_VERSION)
+                             + "\x00" + context).encode()).hexdigest()[:12]
+    return cache_dir(_safe_name(session)) / f"{_safe_name(turn_id)}-{digest}-llm.json"
+
+
+def read_llm_cache(turn_id, session, redacted_text, context):
+    """A reviewer's earlier {keep, summary} for this exact (redacted) text under the same
+    rule call and keep flags (`context`), or None when no reviewer saw it so. Both values
+    null: the reviewer left the turn to the rules."""
+    try:
+        path = _llm_cache_path(turn_id, session, redacted_text, context)
+    except OSError as e:                          # no cache folder (a read-only HOME, say)
+        _warn_once("_no_llm_cache", f"reviewer decision cache unavailable ({e}); "
+                   "every turn is reviewed")
+        return None
+    try:
+        got = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, UnicodeDecodeError):
+        return None
+    if not isinstance(got, dict):
+        return None
+    keep, summary = got.get("keep"), got.get("summary")
+    if not (_is_keep(keep) and _is_summary(summary)):
+        return None
+    return {"keep": keep, "summary": summary}
+
+
+def write_llm_cache(turn_id, session, redacted_text, context, keep, summary):
+    try:
+        _write_private(_llm_cache_path(turn_id, session, redacted_text, context),
+                       json.dumps({"keep": keep, "summary": summary}, ensure_ascii=False))
+    except OSError as e:
+        _warn_once("_no_llm_cache_write", f"reviewer decisions not cached ({e}); the next "
+                   "run reviews this run's turns again (decisions cached before still apply)")
+
+
+def heuristic_drops(turns, args):
+    """{index: why} for the rules' judgement calls: echo exchanges, tool-only turns."""
+    drops = {}
+    if args.drop_trivia:
+        drops.update((i, "echo") for i in echo_indices(turns))
+    if args.hide_tool_only:
+        for i, t in enumerate(turns):
+            if i not in drops and t["role"] == "assistant" and not t["text"].strip():
+                drops[i] = "tool-only"
+    return drops
+
+
+def review_window(turns, drops, args):
+    """Indices for the pack: the turns the range flags pick among those the rules keep
+    (what a --rulebase run shows), the rule-dropped turns between them, and those past
+    either end the pick reaches. None on an invalid --turns."""
+    cand = [i for i, t in enumerate(turns) if _in_time(t, args)]
+    kept = [i for i in cand if i not in drops]
+    pool = kept or cand
+    sl = _count_slice(len(pool), args)
+    if sl is None:
+        return None
+    picked = pool[sl]
+    if not kept or not picked:
+        return picked
+    lo = cand[0] if picked[0] == kept[0] else picked[0]
+    hi = cand[-1] if picked[-1] == kept[-1] else picked[-1]
+    chosen = set(picked)
+    return [i for i in cand if lo <= i <= hi and (i in chosen or i in drops)]
+
+
+def _preview(text):
+    """The reviewer's view of a turn: whole when short, else head + tail."""
+    if len(text) <= PREVIEW_HEAD + PREVIEW_TAIL + 200:
+        return text, False
+    cut = len(text) - PREVIEW_HEAD - PREVIEW_TAIL
+    return (text[:PREVIEW_HEAD].rstrip() + f"\n\n[중간 {cut}자 생략]\n\n"
+            + text[-PREVIEW_TAIL:].lstrip()), True
+
+
+def _public_counts(counts):
+    """Redaction counts by kind with the --redact-extra keywords folded into `custom`:
+    the keywords themselves stay out of the files lineage writes."""
+    out = {}
+    for k, v in counts.items():
+        key = "custom" if k.startswith("custom:") else k
+        out[key] = out.get(key, 0) + v
+    return out
+
+
+def _rule_summary(t, red, args):
+    """The rules' summary for the page, made afresh and redacted with THIS run's settings.
+    The summary cache is keyed on the text alone, so a cached one may predate a
+    --redact-extra keyword or carry another --redact-mode."""
+    if t["role"] in ("assistant", "agent"):
+        return redact(summarize_turn(t), extra=args.redact_extra, mode=args.redact_mode)[0]
+    if t["role"] == "user" and len(red) > USER_FOLD:
+        return user_fold_summary(red)
+    return None
+
+
+def _redacted_turn(t, extra):
+    """`t` with its text and parts fully redacted, so a summary cut from it cannot cut a
+    secret in two and keep the half no pattern recognises."""
+    def clean(s):
+        return review_redact(s, extra)[0]
+    return dict(t, text=clean(t["text"]), parts=[clean(p) for p in t.get("parts") or []])
+
+
+def _review_view(t, red, args):
+    """What a reviewer reads beside the preview: the rules' summary and the agent's
+    name, fully redacted (the page's copies may be masked)."""
+    if t["role"] in ("assistant", "agent"):
+        summary = review_redact(summarize_turn(_redacted_turn(t, args.redact_extra)),
+                                args.redact_extra)[0]
+    elif t["role"] == "user" and len(red) > USER_FOLD:
+        summary = user_fold_summary(review_redact(t["text"], args.redact_extra)[0])
+    else:
+        summary = None
+    who = review_redact(t["agent_from"], args.redact_extra)[0] if t.get("agent_from") else None
+    return {"summary": summary, "agent_from": who}
+
+
+def _pack_turn(n, t, tid, why, session_id, args, counts):
+    """One turn of the pack under its final id `tid` (redacted text, the rules' decision,
+    the reviewer's slot), and the reviewer's view of it."""
+    red, found = redact(t["text"], extra=args.redact_extra, mode=args.redact_mode)
+    for k, v in found.items():
+        counts[k] = counts.get(k, 0) + v
+    preview, clipped = _preview(review_redact(t["text"], args.redact_extra)[0])
+    session = t.get("session") or session_id
+    context = _decision_context(why, _keeps(args))
+    cached = None if args.rebuild_summaries else read_llm_cache(tid, session, red, context)
+    view = _review_view(t, red, args)
+    turn = {"id": tid, "n": n, "role": t["role"], "ts": t.get("ts") or "",
+            "tools": dict(t.get("tools") or {}), "text": red,
+            "redactions": _public_counts(found), "preview": preview, "clipped": clipped,
+            "rule": {"keep": why is None, "why": why,
+                     "summary": _rule_summary(t, red, args),
+                     "review_summary": view["summary"]},
+            "llm": dict(cached, cached=True) if cached else {"keep": None, "summary": None}}
+    if t.get("meta"):
+        turn["meta"] = True
+    for k in ("session", "session_name", "agent_from"):
+        if t.get(k):
+            turn[k] = t[k]
+    return turn, view
+
+
+def _final_ids(turns, window):
+    """Pack ids, fixed before anything reads the decision cache: the turn uuid, with #N
+    on a repeat (stdin uuids are content hashes, so equal texts share one). Counted over
+    every turn, not the window, so a turn keeps its id whichever range is picked."""
+    seen, ids = {}, {}
+    for i, t in enumerate(turns):
+        u = t["uuid"]
+        seen[u] = seen.get(u, 0) + 1
+        ids[i] = u if seen[u] == 1 else f"{u}#{seen[u]}"
+    return [ids[i] for i in window]
+
+
+def _split_even(items, size):
+    """Parts of at most `size` items, as even as possible (41: 21 + 20, not 40 + 1)."""
+    if not items:
+        return []
+    step = -(-len(items) // -(-len(items) // size))
+    return [items[k:k + step] for k in range(0, len(items), step)]
+
+
+def _decisions_name(part_path):
+    return part_path.with_name(part_path.stem + ".decisions.json").name
+
+
+def _clear_parts(pack_path):
+    """Remove the part and decisions files an earlier --emit-review left beside the
+    pack, and an earlier gate's samples: that run's decisions must not be applied to this
+    one, and its samples would stop this pack's rerun. Returns the files it could not
+    remove."""
+    prefix = pack_path.stem + ".part-"
+    samples = f"{pack_path.stem}.reviewer-input.json"
+    try:
+        olds = [p for p in pack_path.parent.iterdir()
+                if (p.name.startswith(prefix) and p.name.endswith(".json")) or p.name == samples]
+    except OSError:
+        return []
+    failed = []
+    for p in olds:
+        try:
+            p.unlink()
+        except OSError:
+            failed.append(p)
+    return failed
+
+
+def _hide_keywords(s, extra):
+    """`s` with each --redact-extra keyword replaced (for short names such as tool names)."""
+    for kw in [k.strip() for k in (extra or "").split(",") if k.strip()]:
+        s = re.sub(re.escape(kw), "[REDACTED]", s, flags=re.IGNORECASE)
+    return s
+
+
+def _keeps(args):
+    """The keep flags the reviewers must honour: with them, the rules keep those turns."""
+    return {"keep_trivia": not args.drop_trivia, "keep_tool_only": not args.hide_tool_only}
+
+
+def _sheet(k, of, part_path, group, args):
+    """Part file `k`: the turns one reviewer reads, without the page-only fields."""
+    turns = []
+    for x, view in group:
+        y = {key: v for key, v in x.items()
+             if key not in ("text", "session", "session_name", "agent_from", "redactions")}
+        y["rule"] = {k: v for k, v in x["rule"].items() if k != "review_summary"}
+        y["rule"]["summary"] = view["summary"]
+        y["tools"] = {_hide_keywords(name, args.redact_extra): n for name, n in x["tools"].items()}
+        if x["llm"].get("summary"):               # cached: redacted for the page, maybe masked
+            s = _MASKED.sub("[REDACTED]", x["llm"]["summary"])
+            y["llm"] = dict(x["llm"], summary=review_redact(s, args.redact_extra)[0])
+        if view["agent_from"]:
+            y["agent_from"] = view["agent_from"]
+        turns.append(y)
+    return {"schema": REVIEW_PART_SCHEMA, "part": k, "of": of, **_keeps(args),
+            "decisions": _decisions_name(part_path), "turns": turns}
+
+
+def _pack_header(session_id, output, args, counts):
+    """The pack's settings: what --apply-review renders with and the quality gate it runs."""
+    return {"schema": REVIEW_SCHEMA, "source": session_id, "output": str(output),
+            "title": args.title, "markdown": args.markdown, "open": args.open_details,
+            "redact_mode": args.redact_mode, "redact_extra": bool(args.redact_extra),
+            "all_sessions": bool(args.all_sessions), "redactions": _public_counts(counts),
+            **_keeps(args),
+            "gate": {"skip_reviewer": bool(args.skip_reviewer),
+                     "reviewer_output": args.reviewer_output,
+                     "reviewer_timeout": args.reviewer_timeout}}
+
+
+def _report_emit(pack_path, items, paths, groups):
+    dropped = sum(1 for x in items if not x["rule"]["keep"])
+    cached = sum(1 for x in items if x["llm"].get("cached"))
+    print(f"[lineage] review pack: {pack_path} (turns={len(items)} "
+          f"rule-dropped={dropped} cached={cached})", file=sys.stderr)
+    for k, (p, g) in enumerate(zip(paths, groups), 1):
+        todo = sum(1 for x, _ in g if not x["llm"].get("cached"))
+        print(f"[lineage] part {k}/{len(groups)}: {p} (to review: {todo}) "
+              f"-> {p.with_name(_decisions_name(p))}", file=sys.stderr)
+    print(f"[lineage] next: write each part's decisions, then "
+          f"--apply-review {pack_path}", file=sys.stderr)
+
+
+def emit_review(turns, drops, window, session_id, output, args):
+    """Write the pack and one part file per reviewer; print them and the next step. A
+    --reviewer-output that holds something other than a verdict list stops it here, before
+    any reviewer runs: the gate would refuse it only after them."""
+    rop = pathlib.Path(args.reviewer_output) if args.reviewer_output and not args.skip_reviewer else None
+    if rop is not None and rop.exists() and not _is_verdict_file(rop):
+        _bad(f"{rop} is there and is not a verdict list; give a --reviewer-output that does not exist yet")
+        return 2
+    pack_path = pathlib.Path(args.emit_review)
+    counts, pairs = {}, []
+    for n, (i, tid) in enumerate(zip(window, _final_ids(turns, window)), 1):
+        pairs.append(_pack_turn(n, turns[i], tid, drops.get(i), session_id, args, counts))
+    groups = _split_even(pairs, REVIEW_PART)
+    paths = [pack_path.with_name(f"{pack_path.stem}.part-{k}.json")
+             for k in range(1, len(groups) + 1)]
+    pack = _pack_header(session_id, _with_timestamp_suffix(output), args, counts)
+    pack["parts"] = [{"part": k, "file": p.name, "decisions": _decisions_name(p),
+                      "ids": [x["id"] for x, _ in g]}
+                     for k, (p, g) in enumerate(zip(paths, groups), 1)]
+    pack["turns"] = [x for x, _ in pairs]
+    stuck = _clear_parts(pack_path)
+    if stuck:
+        _bad(f"cannot remove an earlier run's files: {', '.join(map(str, stuck))}")
+        return 2
+    try:
+        _write_private(pack_path, json.dumps(pack, ensure_ascii=False, indent=1))
+        for k, (p, g) in enumerate(zip(paths, groups), 1):
+            _write_private(p, json.dumps(_sheet(k, len(groups), p, g, args),
+                                         ensure_ascii=False, indent=1))
+    except OSError as e:
+        _bad(f"cannot write the review pack: {e}")
+        return 2
+    _report_emit(pack_path, pack["turns"], paths, groups)
+    return 0
+
+
+def _is_pack_turn(x):
+    return (isinstance(x, dict) and isinstance(x.get("id"), str)
+            and x.get("role") in ("user", "assistant", "agent", "mark")
+            and isinstance(x.get("text"), str)
+            and isinstance(x.get("rule"), dict) and isinstance(x["rule"].get("keep"), bool)
+            and _is_summary(x["rule"].get("summary"))
+            and isinstance(x.get("llm"), dict) and _is_keep(x["llm"].get("keep"))
+            and _is_summary(x["llm"].get("summary")))
+
+
+def _load_pack(path):
+    try:
+        pack = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, UnicodeDecodeError) as e:
+        return _bad(f"cannot read review pack {path}: {e}")
+    if not isinstance(pack, dict) or pack.get("schema") != REVIEW_SCHEMA:
+        return _bad(f"{path} is not a {REVIEW_SCHEMA} pack")
+    if not isinstance(pack.get("turns"), list) or not all(map(_is_pack_turn, pack["turns"])):
+        return _bad(f"{path}: malformed turns")
+    return pack
+
+
+def _decision_files(pack_path, pack, explicit):
+    """The parts' decisions files that exist beside the pack, then each --decisions.
+    Those beside the pack are made 0600: the session wrote them with its own umask."""
+    beside = [pack_path.with_name(p["decisions"]) for p in pack.get("parts") or []
+              if isinstance(p, dict) and isinstance(p.get("decisions"), str)]
+    files, seen = [], set()
+    for f in [f for f in beside if f.exists()] + [pathlib.Path(f) for f in explicit]:
+        if os.path.realpath(str(f)) not in seen:
+            seen.add(os.path.realpath(str(f)))
+            files.append(f)
+    for f in beside:
+        try:
+            os.chmod(str(f), 0o600)
+        except OSError:
+            pass
+    return files
+
+
+# Keys of a part file's turns: a list of objects carrying one is the reviewer quoting its
+# input, not its answer.
+_PART_TURN_KEYS = frozenset({"n", "role", "ts", "tools", "text", "preview", "clipped",
+                             "rule", "llm", "meta", "agent_from"})
+
+
+def _is_answer(d):
+    """A decision, extra keys and all; a part turn quoted back (its keep and summary sit
+    under rule and llm, not on top) is not one."""
+    return (isinstance(d, dict) and "id" in d
+            and ("keep" in d or "summary" in d or not _PART_TURN_KEYS & d.keys()))
+
+
+def _decisions_text(text):
+    """The JSON list in a reviewer's answer: the whole text, or, when the answer came
+    wrapped (a code fence, a sentence with brackets of its own, a list of files or a quote
+    of the part's turns around it), the longest list of {id, ...} objects in it that is
+    not such a quote (the last of equal ones: an example quoted before the answer loses),
+    else an empty list it holds."""
+    try:
+        return json.loads(text)
+    except (ValueError, RecursionError):
+        pass
+    lists, empty = [], False
+    decoder = json.JSONDecoder()
+    # only where a list of objects or an empty list can start: a run of `[` is tried once,
+    # and only so many starts (each failed try parses up to the nesting limit)
+    for k, m in enumerate(re.finditer(r"\[(?=\s*[{\]])", text)):
+        if k == DECISIONS_TRIES:
+            raise ValueError(f"more than {DECISIONS_TRIES} places a list may start; "
+                             "write the bare JSON array")
+        try:
+            got, _ = decoder.raw_decode(text, m.start())
+        except (ValueError, RecursionError):
+            continue
+        if got == []:
+            empty = True
+        elif isinstance(got, list) and all(_is_answer(d) for d in got):
+            lists.append(got)
+    if lists:
+        return max(reversed(lists), key=len)
+    if empty:
+        return []
+    raise ValueError("no JSON list of {id, keep, summary} objects in it")
+
+
+def _decision_problem(d):
+    """Why item `d` of a decisions file is not a decision, or ""."""
+    if not (isinstance(d, dict) and isinstance(d.get("id"), str)
+            and _is_keep(d.get("keep")) and _is_summary(d.get("summary"))):
+        return 'want {"id": str, "keep": true|false|null, "summary": str|null}'
+    if not _is_answer(d):
+        return "a turn of the part file, not a decision"
+    return ""
+
+
+def _load_decisions(files):
+    """{id: {keep, summary}} from the files in order, a later value winning; None when a
+    file is not a JSON list of {id, keep, summary}. A file whose every decision is null
+    is read, with a WARN: the rules then decide all its turns."""
+    merged = {}
+    for f in files:
+        try:
+            if f.stat().st_size > DECISIONS_MAX:
+                raise ValueError(f"larger than {DECISIONS_MAX} bytes")
+            items = _decisions_text(f.read_text(encoding="utf-8"))
+        except (OSError, ValueError, UnicodeDecodeError, RecursionError) as e:
+            return _bad(f"cannot read decisions {f}: {e}")
+        if not isinstance(items, list):
+            return _bad(f"{f}: decisions must be a JSON list of {{id, keep, summary}}")
+        for k, d in enumerate(items):
+            why = _decision_problem(d)
+            if why:
+                return _bad(f"{f}[{k}]: {why}")
+            cur = merged.setdefault(d["id"], {})
+            for key in ("keep", "summary"):
+                if d.get(key) is not None:
+                    cur[key] = d[key]
+        if items and all(d.get("keep") is None and d.get("summary") is None for d in items):
+            print(f"[lineage] WARN: {f}: all {len(items)} decisions are null; the rules "
+                  "decide those turns", file=sys.stderr)
+    return merged
+
+
+def _clean_summary(s, extra, mode):
+    """A reviewer's summary as the page shows it (one line, redacted, then cut), and how
+    many secret-like strings that redaction hid. The reviewer patterns go first and hide
+    a key whole, whatever --redact-mode says: the summary is cached and goes back to the
+    next reviewer and the gate's critic, so no part of a key may stay in it."""
+    pre, n = review_redact(" ".join(s.split()), extra)
+    red, found = redact(pre, extra=extra, mode=mode)
+    return (_cut(red, SUMMARY_MAX) or None), n + sum(found.values())
+
+
+def _warn_coverage(pack, decided):
+    """Name the parts that left turns undecided: the rules decide those, and since only
+    decided turns are cached, they are reviewed again next time."""
+    for p in pack.get("parts") or []:
+        ids = p.get("ids") if isinstance(p, dict) else None
+        if not isinstance(ids, list):
+            continue
+        todo = [i for i in ids if i not in decided]
+        if todo:
+            more = ", ..." if len(todo) > 3 else ""
+            print(f"[lineage] WARN: part {p.get('part')}: {len(todo)}/{len(ids)} turns "
+                  f"undecided ({', '.join(map(str, todo[:3]))}{more}); the rules decide them",
+                  file=sys.stderr)
+
+
+def _reviewer_summary(x, d, args, stats):
+    """The reviewer's summary for pack turn `x` (this run's decision `d`, else the cached
+    one), cleaned; secret-like strings in it are counted and the turn is named."""
+    raw = _first(d.get("summary"), x["llm"].get("summary"))
+    if not raw:
+        return None
+    s, n = _clean_summary(raw, args.redact_extra, args.redact_mode)
+    if n:
+        stats["hidden"] += n
+        print(f"[lineage] WARN: the reviewer summary for {x['id']} held {n} "
+              "secret-like string(s); redacted", file=sys.stderr)
+    return s
+
+
+def _show(x, llm_summary, turns, summaries, stats, prior):
+    """Put kept pack turn `x` on the page with the summary it shows; `prior` adds up what
+    --emit-review redacted."""
+    shows = x["role"] in ("assistant", "agent") or (
+        x["role"] == "user" and len(x["text"]) > USER_FOLD)
+    if llm_summary and not shows:
+        stats["ignored"] += 1
+    summary = (llm_summary if shows else None) or x["rule"].get("summary")
+    if summary:
+        summaries[x["id"]] = summary
+    stats["reviewer" if llm_summary and shows else "rule"] += bool(summary)
+    for k, v in (x.get("redactions") or {}).items():
+        if isinstance(v, int):
+            prior[k] = prior.get(k, 0) + v
+    # what the gate's critic reads: the reviewer's summary, else the rules' cut from the
+    # fully redacted text (the page's is cut first and may keep half a secret)
+    sample = (llm_summary if shows else None) or x["rule"].get("review_summary")
+    turns.append({"uuid": x["id"], "role": x["role"], "text": x["text"],
+                  "ts": x.get("ts") or None, "tools": dict(x.get("tools") or {}),
+                  "parts": [], "session": x.get("session"),
+                  "session_name": x.get("session_name"),
+                  "agent_from": x.get("agent_from"), "preview": x.get("preview"),
+                  "sample_summary": sample})
+
+
+def _kept_by_flag(pack, x):
+    """True when a keep flag given at --emit-review keeps pack turn `x` whatever the
+    reviewer says: --keep-trivia keeps every turn the rules keep, --keep-tool-only the
+    tool-only ones (the rules keep those only with that flag)."""
+    if not x["rule"]["keep"]:
+        return False
+    if pack.get("keep_trivia") is True:
+        return True
+    tool_only = x["role"] == "assistant" and not x["text"].strip()
+    return pack.get("keep_tool_only") is True and tool_only
+
+
+def _review_result(pack, merged, args):
+    """(turns to render, their summaries, cache writes, counts, prior redactions, the ids of
+    turns the user typed that the reviewers dropped) from the pack and the decisions: a
+    reviewer's value first, then the pack's cached one, then the rules'. A keep flag outranks
+    a reviewer's `false`; the cache still gets what was said."""
+    turns, summaries, writes, prior, typed = [], {}, [], {}, []
+    stats = {"restored": 0, "dropped": 0, "reviewer": 0, "rule": 0, "ignored": 0,
+             "hidden": 0, "flag-kept": 0}
+    for x in pack["turns"]:
+        d = merged.get(x["id"], {})
+        llm_keep = _first(d.get("keep"), x["llm"].get("keep"))
+        held = llm_keep is False and _kept_by_flag(pack, x)
+        stats["flag-kept"] += held
+        keep = bool(_first(None if held else llm_keep, x["rule"]["keep"]))
+        if not keep and x["role"] == "user" and x["rule"]["keep"] and not x.get("meta"):
+            typed.append(x["id"])               # typed by the user: the rules keep these
+        llm_summary = _reviewer_summary(x, d, args, stats)
+        if x["id"] in merged:                    # reviewed, even if left to the rules
+            writes.append((x["id"], x.get("session") or pack.get("source"), x["text"],
+                           _decision_context(x["rule"].get("why"), pack), llm_keep, llm_summary))
+        stats["restored"] += keep and not x["rule"]["keep"]
+        stats["dropped"] += x["rule"]["keep"] and not keep
+        if keep:
+            _show(x, llm_summary, turns, summaries, stats, prior)
+    return turns, summaries, writes, stats, prior, typed
+
+
+def _gate_from_pack(args, pack):
+    """The quality-gate flags given at --emit-review, unless this run gives its own."""
+    gate = pack.get("gate") if isinstance(pack.get("gate"), dict) else {}
+    args.skip_reviewer = bool(args.skip_reviewer or gate.get("skip_reviewer") is True)
+    if args.reviewer_output is None and isinstance(gate.get("reviewer_output"), str):
+        args.reviewer_output = gate["reviewer_output"]
+    if args.reviewer_timeout is None and isinstance(gate.get("reviewer_timeout"), int):
+        args.reviewer_timeout = gate["reviewer_timeout"]
+
+
+def _check_pack(pack, merged, args):
+    """Warnings before the render, and the settings the pack carries from --emit-review."""
+    ids = {x["id"] for x in pack["turns"]}
+    unknown = [i for i in merged if i not in ids]
+    if unknown:
+        print(f"[lineage] WARN: decisions name {len(unknown)} turn(s) not in the pack, "
+              f"ignored: {', '.join(unknown[:5])}", file=sys.stderr)
+    _warn_coverage(pack, set(merged) | {x["id"] for x in pack["turns"]
+                                        if x["llm"].get("cached")})
+    if pack.get("redact_mode") in ("full", "mask"):
+        args.redact_mode = pack["redact_mode"]
+    if pack.get("redact_extra") is True and not args.redact_extra:
+        print("[lineage] WARN: --emit-review had --redact-extra; give the same keywords "
+              "here too, or reviewer summaries miss that redaction", file=sys.stderr)
+    _gate_from_pack(args, pack)
+
+
+def _remove_review_files(pack_path, pack):
+    """After a good render the pack, its parts and the decisions beside it go: they hold
+    the redacted session."""
+    samples = f"{pack_path.stem}.reviewer-input.json"      # a failed gate's, beside the pack
+    names = [pack_path.name, samples]
+    for p in pack.get("parts") or []:
+        if isinstance(p, dict):
+            names += [p.get(k) for k in ("file", "decisions") if isinstance(p.get(k), str)]
+    prefix = pack_path.stem + ".part-"
+    left = []
+    for name in names:
+        if name not in (pack_path.name, samples) and not name.startswith(prefix):
+            continue                              # only what --emit-review named
+        try:
+            pack_path.with_name(name).unlink()
+        except FileNotFoundError:
+            pass
+        except (OSError, ValueError):
+            left.append(name)
+    if left:
+        print(f"[lineage] WARN: could not remove review files: {', '.join(left)}",
+              file=sys.stderr)
+
+
+def _samples_left_unread(pack_path, args):
+    """True, with the reason, when a gated run left its samples beside the pack and this run
+    gives neither a verdict path nor --skip-reviewer: it would pass over that run's verdict."""
+    left = pack_path.with_name(f"{pack_path.stem}.reviewer-input.json")
+    if left.exists() and not (args.reviewer_output or args.skip_reviewer):
+        _bad(f"{left} was left by a gated run; give its --reviewer-output again, or --skip-reviewer")
+        return True
+    return False
+
+
+def _review_output(args, pack):
+    """The page path: the pack's when this run gives none, else the given one with the pack's
+    stamp, so the gate's runs write one page."""
+    if args.output is None:
+        return pack.get("output") or "work/lineage-review.html"
+    return _with_pack_stamp(args.output, pack.get("output"))
+
+
+def _report_review(stats, turns, pack, typed):
+    """What the render took from the reviewers, and the turns typed by the user they dropped."""
+    print(f"[lineage] review applied: shown={len(turns)}/{len(pack['turns'])} "
+          f"restored={stats['restored']} dropped={stats['dropped']} "
+          f"summaries reviewer={stats['reviewer']} rule={stats['rule']}", file=sys.stderr)
+    if stats["ignored"]:
+        print(f"[lineage] note: {stats['ignored']} summaries for turns the page shows "
+              "in full were ignored", file=sys.stderr)
+    if stats["flag-kept"]:
+        print(f"[lineage] note: {stats['flag-kept']} turn(s) a reviewer marked keep: false "
+              "stay, as --keep-trivia or --keep-tool-only asked", file=sys.stderr)
+    if typed:
+        print(f"[lineage] WARN: reviewers dropped {len(typed)} typed user turn(s): {', '.join(typed[:10])}"
+              f"{' ...' if len(typed) > 10 else ''}; tell the user", file=sys.stderr)
+
+
+def apply_review(args):
+    """Render from a review pack and its decisions; cache the reviewers' values and, after
+    a good render, remove the review files."""
+    pack_path = pathlib.Path(args.apply_review)
+    pack = _load_pack(pack_path)
+    if pack is None:
+        return 2
+    merged = _load_decisions(_decision_files(pack_path, pack, args.decisions))
+    if merged is None:
+        return 2
+    _check_pack(pack, merged, args)
+    if _samples_left_unread(pack_path, args):
+        return 2
+    turns, summaries, writes, stats, prior, typed = _review_result(pack, merged, args)
+    args.output = _review_output(args, pack)
+    if stats["hidden"]:
+        prior["reviewer-summary"] = stats["hidden"]
+    try:
+        rc = render_and_write(turns, pack.get("source") or "session", args,
+                              all_sessions=bool(pack.get("all_sessions")),
+                              markdown=pack.get("markdown") is not False,
+                              open_details=bool(pack.get("open")),
+                              title=str(pack.get("title") or "Session Lineage"),
+                              summaries=summaries, prior_redactions=prior)
+    except SystemExit as e:                       # the quality gate failed
+        rc = int(e.code) if isinstance(e.code, int) else 2
+    if rc == 0:
+        for w in writes:
+            write_llm_cache(*w)
+        _remove_review_files(pack_path, pack)
+    _report_review(stats, turns, pack, typed)
+    return rc
+
+
 def build_arg_parser() -> argparse.ArgumentParser:
     ap = argparse.ArgumentParser(
         prog="lineage",
@@ -1133,9 +1936,11 @@ def build_arg_parser() -> argparse.ArgumentParser:
                     help="skip reviewer quality gate (warn-only)")
     ap.add_argument("--reviewer-output",
                     help="path to Critic response JSON; enforces the quality gate")
-    ap.add_argument("--reviewer-timeout", type=int, default=60,
-                    help="seconds to wait for reviewer-output (default 60)")
+    ap.add_argument("--reviewer-timeout", type=int, default=None,
+                    help="seconds to wait for reviewer-output (default 60 with --rulebase; "
+                         "the reviewed flow waits only when this is given)")
     ap.add_argument("--title", default="Session Lineage", help="HTML title")
+    _add_review_args(ap)
     # Readability defaults are ON. Opt-out flags restore raw/older behavior.
     ap.add_argument("--hide-tool-only", dest="hide_tool_only", action="store_true",
                     help="(DEFAULT) drop assistant turns that are only tool calls")
@@ -1155,6 +1960,19 @@ def build_arg_parser() -> argparse.ArgumentParser:
     return ap
 
 
+def _add_review_args(ap):
+    """The flags of the reviewed flow (3.0.0): --emit-review, the session's reviewers,
+    then --apply-review."""
+    ap.add_argument("--rulebase", action="store_true",
+                    help="one pass, rules only (the default when no review flag is given)")
+    ap.add_argument("--emit-review", metavar="PACK",
+                    help="write the turns for the session model to review (JSON) and stop")
+    ap.add_argument("--apply-review", metavar="PACK",
+                    help="render from a review pack and the reviewer's decisions")
+    ap.add_argument("--decisions", action="append", default=[], metavar="FILE",
+                    help="reviewer decisions [{id, keep, summary}] for --apply-review (repeatable)")
+
+
 def _open_stream(path):
     return open(path, encoding="utf-8", errors="strict")
 
@@ -1172,6 +1990,21 @@ def _load_turns_from(path, unsafe_schema, session_id, session_name):
         return []
 
 
+def _flag_clash(args):
+    """The review flags that cannot go together, as one message; None when they can."""
+    if args.emit_review == "" or args.apply_review == "":
+        return "--emit-review and --apply-review need a file path"
+    if args.purge_cache and (args.emit_review or args.apply_review):
+        return "--purge-cache is its own run: it takes no review pack"
+    if args.emit_review and args.apply_review:
+        return "--emit-review and --apply-review are two separate runs"
+    if args.rulebase and (args.emit_review or args.apply_review):
+        return "--rulebase is the one-pass run: it takes no review pack"
+    if args.decisions and not args.apply_review:
+        return "--decisions goes with --apply-review"
+    return None
+
+
 def main(argv=None) -> int:
     args = build_arg_parser().parse_args(argv)
 
@@ -1180,6 +2013,11 @@ def main(argv=None) -> int:
         args.redact_extra = ",".join(
             p for p in (args.redact_extra, env_extra) if p)
 
+    clash = _flag_clash(args)
+    if clash:
+        print(f"[lineage] ERROR: {clash}", file=sys.stderr)
+        return 2
+
     if args.purge_cache:
         import shutil
         if CACHE_BASE.exists():
@@ -1189,6 +2027,13 @@ def main(argv=None) -> int:
             print("[lineage] no cache to purge", file=sys.stderr)
         return 0
 
+    if args.apply_review:
+        if any((args.last, args.from_, args.to, args.turns, args.session,
+                args.all_sessions, args.from_transcript)):
+            print("[lineage] note: --apply-review renders the pack; source and range "
+                  "flags were applied at --emit-review", file=sys.stderr)
+        return apply_review(args)
+
     # ---- Resolve input → raw turns (parse + parts + session) ----
     turns = []
     session_id = "session"
@@ -1249,51 +2094,95 @@ def main(argv=None) -> int:
     # stdin → derive per-turn uuid from content hash so cache works
     if args.from_transcript == "-":
         for t in turns:
-            t["uuid"] = hashlib.sha256(t["text"].encode()).hexdigest()[:16]
+            t["uuid"] = hashlib.sha256(str(t["text"]).encode()).hexdigest()[:16]
 
     # ---- Pipeline order (R6): classify → merge → echo → hide-tool-only → range ----
     turns = classify_turns(turns, drop_trivia=args.drop_trivia)
     turns = merge_assistant_runs(turns)
+    if args.emit_review:
+        drops = heuristic_drops(turns, args)
+        window = review_window(turns, drops, args)
+        if window is None:
+            return 2
+        return emit_review(turns, drops, window, session_id,
+                           default_output(args, jsonl_path, session_id), args)
     if args.drop_trivia:
         turns = drop_echo_exchanges(turns)
     if args.hide_tool_only:
         turns = [t for t in turns
                  if not (t["role"] == "assistant" and not t["text"].strip())]
-    if args.from_:
-        turns = [t for t in turns if (t["ts"] or "") >= args.from_]
-    if args.to:
-        # A bare date bound is inclusive of the WHOLE end day: a full ISO
-        # timestamp sorts AFTER the date string ("...T10:..." <= "2026-08-09"
-        # is False), so append a high sentinel for date-only input.
-        to_bound = args.to if "T" in args.to else args.to + "T99"
-        turns = [t for t in turns if (t["ts"] or "") <= to_bound]
+    turns = select_range(turns, args)
+    if turns is None:
+        return 2
+    if args.output is None:
+        args.output = default_output(args, jsonl_path, session_id)
+    return render_and_write(turns, session_id, args, all_sessions=args.all_sessions,
+                            markdown=args.markdown, open_details=args.open_details,
+                            title=args.title)
+
+
+def _in_time(t, args):
+    """--from / --to on one turn. A bare date bound is inclusive of the WHOLE end
+    day: a full ISO timestamp sorts AFTER the date string ("...T10:..." <=
+    "2026-08-09" is False), so a high sentinel is appended for date-only input."""
+    ts = t["ts"] or ""
+    if args.from_ and ts < args.from_:
+        return False
+    if args.to and ts > (args.to if "T" in args.to else args.to + "T99"):
+        return False
+    return True
+
+
+def _count_slice(n, args):
+    """--turns then --last over n items, as a slice; None on an invalid --turns."""
+    lo, hi = 0, n
     if args.turns:
         m = re.match(r"^(\d+)-(\d+)$", args.turns)
         if not m:
             print(f"[lineage] invalid --turns '{args.turns}'", file=sys.stderr)
-            return 2
-        lo, hi = max(1, int(m.group(1))), int(m.group(2))
-        turns = turns[lo - 1:hi]
+            return None
+        lo, hi = max(1, int(m.group(1))) - 1, min(int(m.group(2)), n)
     if args.last and args.last > 0:
-        turns = turns[-args.last:]
+        lo = max(lo, hi - args.last)
+    return slice(lo, hi)
+
 
+def select_range(turns, args):
+    """--from / --to / --turns / --last, in that order; None on an invalid --turns."""
+    turns = [t for t in turns if _in_time(t, args)]
+    sl = _count_slice(len(turns), args)
+    if sl is None:
+        return None
+    turns = turns[sl]
     if len(turns) > 100:
         print(f"[lineage] WARN: {len(turns)} turns is large — render may be slow",
               file=sys.stderr)
+    return turns
 
-    # ---- Resolve default output path ----
-    if args.output is None:
-        session_name = discover_session_name(jsonl_path) if jsonl_path else None
-        slug = ("all-sessions" if args.all_sessions
-                else (session_name or session_id[:8]))
-        args.output = f"work/lineage-{slug}.html"
-        if session_name:
-            print(f"[lineage] session name: {session_name}", file=sys.stderr)
 
+def default_output(args, jsonl_path, session_id):
+    """work/lineage-<session name or id>.html, or args.output when given."""
+    if args.output is not None:
+        return args.output
+    session_name = discover_session_name(jsonl_path) if jsonl_path else None
+    slug = ("all-sessions" if args.all_sessions
+            else (session_name or session_id[:8]))
+    if session_name:
+        print(f"[lineage] session name: {session_name}", file=sys.stderr)
+    return f"work/lineage-{slug}.html"
+
+
+def render_and_write(turns, session_id, args, all_sessions=False, markdown=True,
+                     open_details=False, title="Session Lineage", summaries=None,
+                     prior_redactions=None):
+    """Render the rows, fill the template, self-verify, write, run the reviewer gate.
+    `prior_redactions`: what --emit-review redacted before the text reached the pack."""
     rows, redact_counts, hits, total = render_rows(
         turns, session_id, args.redact_extra, args.redact_mode,
-        args.rebuild_summaries, open_details=args.open_details,
-        markdown=args.markdown, all_sessions=args.all_sessions)
+        args.rebuild_summaries, open_details=open_details,
+        markdown=markdown, all_sessions=all_sessions, summaries=summaries)
+    for k, v in (prior_redactions or {}).items():
+        redact_counts[k] = redact_counts.get(k, 0) + v
 
     date_range = ""
     dated = [t for t in turns if t.get("ts")]
@@ -1303,8 +2192,8 @@ def main(argv=None) -> int:
         date_range = first if first == last else f"{first} ~ {last}"
 
     html_doc = HTML_TEMPLATE
-    html_doc = html_doc.replace("{{TITLE}}", html.escape(args.title), 1)
-    html_doc = html_doc.replace("{{HEADER_TITLE}}", html.escape(args.title), 1)
+    html_doc = html_doc.replace("{{TITLE}}", html.escape(title), 1)
+    html_doc = html_doc.replace("{{HEADER_TITLE}}", html.escape(title), 1)
     html_doc = html_doc.replace("{{DATE_RANGE}}", html.escape(date_range), 1)
     html_doc = html_doc.replace("{{TURNS}}", "\n".join(rows), 1)
 
@@ -1316,7 +2205,7 @@ def main(argv=None) -> int:
     out.parent.mkdir(parents=True, exist_ok=True)
     out.write_text(html_doc, encoding="utf-8")
 
-    _run_reviewer_gate(turns, out, session_id, args)
+    _run_reviewer_gate(turns, out, session_id, args, summaries=summaries)
 
     tool_total = sum(sum(t.get("tools", {}).values()) for t in turns)
     print(f"[lineage] turns={len(turns)} redacted={sum(redact_counts.values())} "
@@ -1328,6 +2217,16 @@ def main(argv=None) -> int:
     return 0
 
 
+def _with_pack_stamp(output, pack_output):
+    """`output` with the `_YYMMDD+HHMM` stamp of the pack's own output, so the gate's runs
+    minutes apart write one page; as given when it has a stamp or the pack's output has none."""
+    stamp = re.search(r"_\d{6}\+\d{4}$", pathlib.Path(str(pack_output or "")).stem)
+    out = pathlib.Path(output)
+    if stamp and not re.search(r"_\d{6}\+\d{4}$", out.stem):
+        return str(out.with_name(f"{out.stem}{stamp.group(0)}{out.suffix}"))
+    return output
+
+
 def _with_timestamp_suffix(path_str):
     """Append `_YYMMDD+HHMM` before the extension (idempotent)."""
     import datetime as _dt
@@ -1338,70 +2237,273 @@ def _with_timestamp_suffix(path_str):
     return p.with_name(f"{p.stem}{stamp}{p.suffix}")
 
 
-def _run_reviewer_gate(turns, out, session_id, args):
-    """Write reviewer samples and (if --reviewer-output) enforce the gate.
-    Uses the new summarizer; the input/output contract is unchanged (N3)."""
-    bots = [t for t in turns if t["role"] in ("assistant", "agent")]
-    if not args.skip_reviewer and bots:
-        import random
-        sample = random.sample(bots, min(5, len(bots)))
-        review_samples = []
-        for i, t in enumerate(sample):
-            s, _ = read_or_summarize(t, session_id, rebuild=False,
-                                     redact_extra=args.redact_extra,
-                                     redact_mode=args.redact_mode)
+def _gate_samples(bots, summaries, session_id, args):
+    """Up to 5 bot turns as the gate's critic reads them. --rulebase keeps the 2.x shape
+    (random turns, page redaction). With reviewer summaries (the default flow) the pick is
+    seeded by the turns, so a rerun on the same turns samples the same ones, and a sample
+    names its turn and shows the head and tail the reviewer saw, fully redacted."""
+    import random
+    if summaries is None:
+        out = []
+        for i, t in enumerate(random.sample(bots, min(5, len(bots)))):
+            s, _ = _page_summary(t, summaries, session_id, False,
+                                 args.redact_extra, args.redact_mode)
             red_s, _ = redact(s, extra=args.redact_extra, mode=args.redact_mode)
-            red_d, _ = redact(t["text"][:500], extra=args.redact_extra,
-                              mode=args.redact_mode)
-            review_samples.append({"idx": i, "original_detail": red_d,
-                                   "generated_summary": red_s})
-        review_path = out.parent / f".{out.stem}.reviewer-input.json"
+            red_d, _ = redact(t["text"][:500], extra=args.redact_extra, mode=args.redact_mode)
+            out.append({"idx": i, "original_detail": red_d, "generated_summary": red_s})
+        return out
+    seed = hashlib.sha256("\x00".join(t["uuid"] for t in bots).encode()).hexdigest()
+    out = []
+    for i, t in enumerate(random.Random(seed).sample(bots, min(5, len(bots)))):
+        s = t.get("sample_summary") or _page_summary(t, summaries, session_id, False,
+                                                     args.redact_extra, args.redact_mode)[0]
+        detail = t.get("preview") or _preview(review_redact(t["text"], args.redact_extra)[0])[0]
+        gen = review_redact(_MASKED.sub("[REDACTED]", s), args.redact_extra)[0]
+        key = hashlib.sha256("\x00".join([t["uuid"], detail, gen]).encode()).hexdigest()[:12]
+        out.append({"idx": i, "id": t["uuid"], "key": key, "original_detail": detail,
+                    "generated_summary": gen})
+    return out
+
+
+# What --redact-mode mask leaves of a secret (4 characters, ****, 4 characters): the page
+# keeps it, a model reading the gate samples gets none of it.
+_MASKED = re.compile(r"[^\s*]{4}\*{4}[^\s*]{4}")
+
+
+def _renew_samples(path, text, rop):
+    """Write the reviewed flow's samples unless they are there as they are. New samples set
+    aside a verdict list already at `rop` (_refuse_non_verdict has stopped on anything
+    else): no critic judged them in it (a --rulebase gate or an earlier sample set left
+    it). The same samples keep a verdict: a critic answered an earlier run, and this run
+    reads that answer."""
+    try:
+        if path.read_text(encoding="utf-8") == text:
+            return
+    except (OSError, UnicodeDecodeError):
+        pass
+    _write_private(path, text)
+    old = pathlib.Path(rop) if rop else None
+    if old is not None and _is_verdict_file(old):
+        print(f"[lineage] WARN: {rop} predates these samples; it is not read",
+              file=sys.stderr)
+        _set_aside(old)
+
+
+def _refuse_non_verdict(rop):
+    """Stop (exit 2) before any sample or instruction when the reviewed flow's verdict path
+    holds something other than a verdict list: whoever put it there, nothing printed here
+    may lead the session to write over it."""
+    p = pathlib.Path(rop) if rop else None
+    if p is None or not p.exists() or _is_verdict_file(p):
+        return
+    if _json_list(p):   # step 8: written again, the same answer fails the same way
+        why = ("it is a JSON array where no entry names idx; if the session wrote the critic's "
+               "answer, have the critic judge the samples again (a failed gate run)")
+    else:
+        why = ("if the session wrote it, write it again as a bare JSON array of "
+               "{idx, id, key, recoverable, reason}")
+    print(f"[lineage] ERROR: {rop} is not a verdict list; {why}, else give a --reviewer-output "
+          "that does not exist yet", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def _json_list(p):
+    """True when `p` is a file holding a JSON array, whatever its entries."""
+    try:
+        return p.is_file() and isinstance(json.loads(p.read_text(encoding="utf-8")), list)
+    except (OSError, ValueError, UnicodeDecodeError, RecursionError):
+        return False
+
+
+def _is_verdict_file(p, every=False):
+    """True when `p` is a file holding a critic's verdict: a JSON list with at least one
+    object that names an `idx`. A list of anything else (a user's data file) is not one; a
+    verdict with an entry short of its idx is one, and the coverage check says what it
+    misses. With `every`, each entry must be such an object: only that file may be written
+    over, so a user's list holding one such object among other data stays."""
+    if not p.is_file():
+        return False
+    try:
+        got = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, ValueError, UnicodeDecodeError, RecursionError):
+        return False
+    if not isinstance(got, list):
+        return False
+    named = [isinstance(v, dict) and "idx" in v for v in got]
+    return bool(named) and all(named) if every else any(named)
+
+
+def _write_gate_samples(bots, out, summaries, session_id, args):
+    """Write the samples for the critic and say what to do with them; their path, or None.
+    The reviewed flow writes them beside the pack, under one name across its reruns, and
+    stops (exit 2) when it cannot: no critic could judge them."""
+    if summaries is not None:
+        _refuse_non_verdict(args.reviewer_output)
+    path = out.parent / f".{out.stem}.reviewer-input.json"
+    if summaries is not None and getattr(args, "apply_review", None):
+        pack = pathlib.Path(args.apply_review)
+        path = pack.with_name(f"{pack.stem}.reviewer-input.json")
+    text = json.dumps(_gate_samples(bots, summaries, session_id, args),
+                      ensure_ascii=False, indent=2)
+    try:
+        if summaries is None:
+            _write_private(path, text)
+        else:
+            _renew_samples(path, text, args.reviewer_output)
+    except OSError as e:
+        if summaries is not None:
+            print(f"[lineage] ERROR: cannot write the gate samples {path}: {e}", file=sys.stderr)
+            raise SystemExit(2)
+        return None
+    print(f"[lineage] reviewer samples: {path}", file=sys.stderr, flush=True)
+    if summaries is None:
+        print("[lineage] next: invoke Skill('oh-my-claudecode:critic') with "
+              "the JSON above; expected [{idx, recoverable, reason}, ...] "
+              "(PASS = 5/5 recoverable)", file=sys.stderr, flush=True)
+    elif pathlib.Path(args.reviewer_output).exists():
+        print(f"[lineage] reading the verdict at {args.reviewer_output}", file=sys.stderr, flush=True)
+    else:
+        print(f"[lineage] next: have a critic agent judge the JSON above and write its "
+              f"[{{idx, id, key, recoverable, reason}}, ...] to {args.reviewer_output} "
+              "(one per sample; PASS = all recoverable)", file=sys.stderr, flush=True)
+    return path
+
+
+def _read_verdict(rop, timeout, set_aside):
+    """The critic's verdict list from `rop`, waited for up to `timeout` seconds (None: not
+    waited for, the next run reads it). With `set_aside` a verdict list is renamed once read,
+    so a rerun waits for a fresh one instead of reusing it; anything else stays where it is.
+    Exits 2 when it is missing, unreadable or not a non-empty list."""
+    import time as _time
+    deadline = _time.time() + (0 if timeout is None else max(1, timeout))
+    while not rop.exists() and _time.time() < deadline:
+        _time.sleep(1)
+    if not rop.exists():
+        if timeout is None:
+            print(f"[lineage] ERROR: no verdict at {rop} yet; have a critic judge the samples, "
+                  "write its answer there and run this again", file=sys.stderr)
+        else:
+            print(f"[lineage] ERROR: reviewer-output not found within "
+                  f"{timeout}s: {rop}", file=sys.stderr)
+        raise SystemExit(2)
+    try:
+        verdict = json.loads(rop.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeDecodeError, RecursionError) as e:
+        print(f"[lineage] ERROR: reviewer-output parse failed: {e}",
+              file=sys.stderr)
+        raise SystemExit(2)
+    if not isinstance(verdict, list) or not verdict:
+        print("[lineage] ERROR: reviewer-output is not a non-empty array",
+              file=sys.stderr)
+        raise SystemExit(2)
+    if set_aside:
+        _set_aside(rop)
+    return verdict
+
+
+def _set_aside(rop):
+    """Rename the verdict file to `<name>.used` and say so; a folder or other non-file at
+    that path is left alone. Something other than an earlier verdict at `<name>.used` is
+    kept too: the verdict then goes to the first `<name>.used.N` that is free or holds an
+    earlier verdict."""
+    if not rop.is_file():
+        print(f"[lineage] WARN: {rop} is not a file; left in place", file=sys.stderr)
+        return
+    dest = rop.with_name(rop.name + ".used")
+    k = 0
+    while dest.exists() and not _is_verdict_file(dest, every=True):
+        k += 1
+        dest = rop.with_name(f"{rop.name}.used.{k}")
+    try:
+        os.replace(str(rop), str(dest))
+    except OSError as e:
+        print(f"[lineage] WARN: could not set the verdict aside ({e}); remove {rop} "
+              "before the next run", file=sys.stderr)
+        return
+    print(f"[lineage] note: verdict moved to {dest}", file=sys.stderr)
+
+
+def _verdict_gaps(verdict, samples):
+    """Why a verdict does not answer these samples, or "": it needs one entry per sample
+    idx and no other, each carrying the `id` and `key` of that sample (its turn and its
+    content: an answer to the samples from before a fix carries an old key)."""
+    want = {s["idx"]: s for s in samples if isinstance(s, dict) and type(s.get("idx")) is int}
+    seen, stray = set(), []
+    for v in verdict:
+        idx = v.get("idx") if isinstance(v, dict) else None
+        if (type(idx) is not int or idx not in want or idx in seen
+                or any(v.get(k) != want[idx][k] for k in ("id", "key") if k in want[idx])):
+            stray.append(idx)
+        else:
+            seen.add(idx)
+    missing = sorted(set(want) - seen)
+    if not (missing or stray):
+        return ""
+    return f"missing idx {missing}, entries that match no sample {stray}"
+
+
+def _check_coverage(verdict, samples):
+    """Exit 2 unless the verdict answers each of the samples in file `samples`."""
+    try:
+        gaps = _verdict_gaps(verdict, json.loads(samples.read_text(encoding="utf-8")))
+    except (OSError, ValueError, UnicodeDecodeError, AttributeError) as e:
+        gaps = f"cannot read the samples: {e}"
+    if gaps:
+        print(f"[lineage] ERROR: the verdict does not answer {samples} ({gaps}); have the "
+              "critic judge every sample again", file=sys.stderr)
+        for v in verdict:
+            if isinstance(v, dict) and v.get("recoverable") is not True:
+                print(f"  - not recoverable in it: idx={v.get('idx', '?')}: "
+                      f"{v.get('reason', '(no reason)')}", file=sys.stderr)
+        raise SystemExit(2)
+
+
+def _enforce_gate(rop, timeout, samples=None, reviewed=False):
+    """PASS when every verdict entry is recoverable, else exit 2 with the reasons. In the
+    reviewed flow the verdict is set aside once read, it must answer each sample, and the
+    samples go after a PASS."""
+    verdict = _read_verdict(rop, timeout, set_aside=reviewed)
+    if reviewed and samples is not None:
+        _check_coverage(verdict, samples)
+    fails = [v for v in verdict
+             if not (isinstance(v, dict) and v.get("recoverable") is True)]
+    if fails:
+        print(f"[lineage] FAIL: quality gate {len(verdict) - len(fails)}/"
+              f"{len(verdict)} recoverable. Reasons:", file=sys.stderr)
+        for f in fails:
+            if isinstance(f, dict):
+                print(f"  - idx={f.get('idx', '?')}: "
+                      f"{f.get('reason', '(no reason)')}", file=sys.stderr)
+        raise SystemExit(2)
+    print(f"[lineage] PASS: quality gate {len(verdict)}/{len(verdict)} "
+          "recoverable", file=sys.stderr)
+    if reviewed and samples is not None:
         try:
-            review_path.write_text(
-                json.dumps(review_samples, ensure_ascii=False, indent=2),
-                encoding="utf-8")
-            print(f"[lineage] reviewer samples: {review_path}", file=sys.stderr)
-            print("[lineage] next: invoke Skill('oh-my-claudecode:critic') with "
-                  "the JSON above; expected [{idx, recoverable, reason}, ...] "
-                  "(PASS = 5/5 recoverable)", file=sys.stderr)
+            samples.unlink()
         except OSError:
             pass
-    elif args.skip_reviewer:
+
+
+def _run_reviewer_gate(turns, out, session_id, args, summaries=None):
+    """Write reviewer samples and (if --reviewer-output) enforce the gate. Samples the
+    summaries the page shows (`summaries` overrides, as in render_rows); the input/output
+    contract is unchanged (N3). The reviewed flow (`summaries` given) already had a model
+    review every turn, so it samples only for a gate it enforces."""
+    bots = [t for t in turns if t["role"] in ("assistant", "agent")]
+    reviewed = summaries is not None
+    if args.skip_reviewer:
         print("[lineage] WARN: --skip-reviewer — quality gate not enforced",
               file=sys.stderr)
-
-    if (not args.skip_reviewer) and bots and args.reviewer_output:
-        import time as _time
-        rop = pathlib.Path(args.reviewer_output)
-        deadline = _time.time() + max(1, args.reviewer_timeout)
-        while not rop.exists() and _time.time() < deadline:
-            _time.sleep(1)
-        if not rop.exists():
-            print(f"[lineage] ERROR: reviewer-output not found within "
-                  f"{args.reviewer_timeout}s: {rop}", file=sys.stderr)
-            raise SystemExit(2)
-        try:
-            verdict = json.loads(rop.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError, UnicodeDecodeError) as e:
-            print(f"[lineage] ERROR: reviewer-output parse failed: {e}",
-                  file=sys.stderr)
-            raise SystemExit(2)
-        if not isinstance(verdict, list) or not verdict:
-            print("[lineage] ERROR: reviewer-output is not a non-empty array",
-                  file=sys.stderr)
-            raise SystemExit(2)
-        fails = [v for v in verdict
-                 if not (isinstance(v, dict) and v.get("recoverable") is True)]
-        if fails:
-            print(f"[lineage] FAIL: quality gate {len(verdict) - len(fails)}/"
-                  f"{len(verdict)} recoverable. Reasons:", file=sys.stderr)
-            for f in fails:
-                if isinstance(f, dict):
-                    print(f"  - idx={f.get('idx', '?')}: "
-                          f"{f.get('reason', '(no reason)')}", file=sys.stderr)
-            raise SystemExit(2)
-        print(f"[lineage] PASS: quality gate {len(verdict)}/{len(verdict)} "
-              "recoverable", file=sys.stderr)
+        return
+    if not bots or (reviewed and not args.reviewer_output):
+        return
+    samples = _write_gate_samples(bots, out, summaries, session_id, args)
+    if args.reviewer_output:
+        if reviewed and args.reviewer_timeout is None:
+            timeout = None      # the run after the critic reads the verdict; this one does not wait
+        else:
+            timeout = REVIEWER_TIMEOUT if args.reviewer_timeout is None else args.reviewer_timeout
+        _enforce_gate(pathlib.Path(args.reviewer_output), timeout, samples, reviewed)
 
 
 if __name__ == "__main__":