task-pipeline-skill 1.93.2 → 1.94.1

package/plugins/task-pipeline/skills/task-pipeline/scripts/stage_checkpoint.py

@@ -15,8 +15,10 @@ deterministic halves around that call, so nothing about the checkpoint is left t
         prints the tool's arguments as JSON, from the ledger's last `stage:` line
     stage_checkpoint.py record --answer FILE|-   [--ledger PATH]
         reads the tool's answer and keeps `workflowId` and `leaseId` for the next boundary
-    stage_checkpoint.py record --unavailable "<reason>"   [--ledger PATH]
-        the tools are absent or failed: one ledger line, exit 0, the run continues
+    stage_checkpoint.py record --unavailable "<reason>" [--for-run]   [--ledger PATH]
+        the tools are absent or failed: one ledger line, exit 0, the run continues.
+        --for-run says it once for the whole run: a marker in memory.json silences
+        hooks/memory-nudge.sh until a later `record --answer` clears it
     stage_checkpoint.py state  [--ledger PATH]
         the workflow this run writes to, for `observatory_checkpoint_latest` after a resume
 
@@ -45,6 +47,7 @@ Ledger lines it appends, all of the existing `event:` shape:
     event: memory — checkpoint <stepId> rev <n> <workflowId> — <ISO-8601>
     event: memory — refused <error> (kept as <id>) — <ISO-8601>
     event: memory — unavailable — <reason> — <ISO-8601>
+    event: memory — unavailable for this run — <reason> — <ISO-8601>
 
 Exit codes: 0 done (including "unavailable", which is a state, not a failure); 2 the ledger
 or the answer cannot be read.
@@ -71,6 +74,10 @@ TOPIC = re.compile(r"^Run:\s*`([^`]+)`")
 # passes a surface took is measured at the boundary rather than remembered at the end.
 REVIEW = re.compile(r"^review:\s*(\d+)\s+—\s+surface\s+(.+?)\s+—\s+rounds\s+(\d+)\s+—\s+(\S+)\s+—\s+\S+\s*$")
 STATUS = {"pass": "done", "skip": "done", "fail": "blocked"}
+# What `handoff` counts for its idempotency key: the memory events this script appended
+# (checkpoint, refused, handoff offered) — never `unavailable`, which records no state change.
+MEMORY_EVENT = re.compile(r"^event:\s*memory\s+—\s")
+MEMORY_UNAVAILABLE = re.compile(r"^event:\s*memory\s+—\s+unavailable\b")
 
 
 def _stages() -> dict[int, str]:
@@ -99,16 +106,44 @@ def _reviews(path: pathlib.Path) -> dict[int, list[str]]:
     return out
 
 
+def run_line(lines: list[str]) -> str | None:
+    """The run's `Run:` line — the first one naming a real topic, not the template's.
+
+    ONE helper for everything that asks "which run is this": `_read_ledger` takes the topic
+    from it, and `run_key` hashes it for the run-level memory marker and for
+    `hooks/memory-nudge.sh`'s once-per-run pointer, which imports this function."""
+    for line in lines:
+        m = TOPIC.match(line)
+        if m and "<topic>" not in m.group(1):
+            return line.strip()
+    return None
+
+
+STARTED = re.compile(r"started\s*`([^`]+)`")
+
+
+def run_key(lines: list[str]) -> str | None:
+    """16 hex of the run's topic and start date — not the whole `Run:` line, whose module-map
+    field an agent may fill in mid-run. The same topic started on another day is another run;
+    a same-day restart is told apart by `marker_for_this_run`'s ledger-line test."""
+    line = run_line(lines)
+    if not line:
+        return None
+    topic = TOPIC.match(line).group(1)
+    started = STARTED.search(line)
+    ident = f"{topic}\n{started.group(1) if started else ''}"
+    return hashlib.sha256(ident.encode()).hexdigest()[:16]
+
+
 def _read_ledger(path: pathlib.Path) -> tuple[str, list[tuple]]:
     try:
         text = path.read_text(encoding="utf-8")
     except OSError as exc:
         raise SystemExit(f"stage_checkpoint: the ledger {path} cannot be read ({type(exc).__name__})")
-    topic, stages = None, []
-    for line in text.splitlines():
-        m = TOPIC.match(line)
-        if m and topic is None and "<topic>" not in m.group(1):
-            topic = m.group(1)
+    lines = text.splitlines()
+    rl = run_line(lines)
+    topic, stages = (TOPIC.match(rl).group(1) if rl else None), []
+    for line in lines:
         s = STAGE.match(line)
         if s:
             stages.append((int(s.group(1)), s.group(2), s.group(3), s.group(4), s.group(5), line))
@@ -117,6 +152,30 @@ def _read_ledger(path: pathlib.Path) -> tuple[str, list[tuple]]:
     return topic, stages
 
 
+class UsageError(Exception):
+    """A call the script cannot act on as given: exit 2, nothing written."""
+
+
+def marker_for_this_run(ledger: pathlib.Path, state: dict) -> dict | None:
+    """The run-level "memory unavailable" marker, only when it was written for THIS run.
+
+    Two tests, both needed: the run key (topic and start date) matches, AND the marker's own
+    `unavailable for this run` line is still in the ledger. A ledger reseeded at stage 0 the
+    same day carries an identical `Run:` line but not that line, so a restart never inherits
+    the previous run's silence (verification round 3)."""
+    gone = (state.get("memory") or {}).get("unavailable") or {}
+    if not gone:
+        return None
+    try:
+        lines = ledger.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return None
+    key = run_key(lines)
+    if key is None or gone.get("run") != key or gone.get("ledger_line") not in lines:
+        return None
+    return gone
+
+
 def _state_path(ledger: pathlib.Path) -> pathlib.Path:
     return ledger.parent / STATE_NAME
 
@@ -217,10 +276,36 @@ def emit(ledger: pathlib.Path, project: str | None, constraints: list[str],
     return args
 
 
-def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | None) -> str:
+def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | None,
+           for_run: bool = False) -> str:
     if unavailable is not None:
         reason = " ".join(unavailable.split())[:200] or "no reason given"
-        line = f"event: memory — unavailable — {reason} — {_now()}"
+        if for_run:
+            # ONE marker for the run (CHANGELOG, Unreleased). Without it a run on a machine with no
+            # Observatory paid one nudge and one ledger line per gate — about eleven of
+            # each — to restate a fact that does not change between gates.
+            # The marker carries the run key (topic and start date, hashed): the hook and
+            # `state` honour it only while the ledger names the same run AND still carries this
+            # line, so a marker left on disk — even after a same-day reseed — cannot silence
+            # the next run.
+            try:
+                key = run_key(ledger.read_text(encoding="utf-8").splitlines())
+            except OSError:
+                key = None
+            if key is None:
+                raise UsageError("--for-run needs the ledger's `Run:` line: the marker is "
+                                 "keyed to the run, and a ledger that names no run has none")
+            line = f"event: memory — unavailable for this run — {reason} — {_now()}"
+            state = _load_state(ledger)
+            state["memory"] = {"unavailable": {"reason": reason, "at": _now(), "ledger_line": line,
+                                               "run": key}}
+            _save_state(ledger, state)
+        else:
+            line = f"event: memory — unavailable — {reason} — {_now()}"
+            state = _load_state(ledger)
+            if state.get("memory") and marker_for_this_run(ledger, state) is None:
+                state.pop("memory")  # another run's marker: cleared, not inherited
+                _save_state(ledger, state)
         _append(ledger, line)
         return line
     try:
@@ -230,6 +315,9 @@ def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | Non
     if not isinstance(answer, dict):
         raise SystemExit("stage_checkpoint: the answer is not an object")
     state = _load_state(ledger)
+    # Any answer — a checkpoint or a refusal — means the tools answered: the run-level
+    # "unavailable" marker no longer holds, and the nudge comes back.
+    cleared = state.pop("memory", None) is not None
     if answer.get("error"):
         kept = answer.get("keptAs")
         if answer["error"] in ("LeaseLost", "WorkflowClosed"):
@@ -240,9 +328,13 @@ def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | Non
             _save_state(ledger, state)
         line = (f"event: memory — refused {answer['error']}"
                 f"{f' (kept as {kept})' if kept else ''} — {_now()}")
+        if cleared:
+            _save_state(ledger, state)
         _append(ledger, line)
         return line
     if answer.get("handoffId") and not answer.get("leaseId"):
+        if cleared:
+            _save_state(ledger, state)
         # An offer: the lease stays with this run until the successor accepts.
         line = f"event: memory — handoff offered {answer['handoffId']} — {_now()}"
         _append(ledger, line)
@@ -276,11 +368,15 @@ def handoff(ledger: pathlib.Path, provider: str, model: str | None, reason: str,
                          "(emit → observatory_checkpoint_write → record)")
     to = {"provider": provider, **({"model": model} if model else {})}
     # Observatory digests the whole request, TTL included, so the TTL is in the key (another
-    # TTL is another offer, not an idempotency conflict). So is the ledger's length: once an
-    # offer is recorded the ledger grows, and offering again after it lapsed is a new offer —
-    # the same key would replay the first, expired answer. A retry before recording repeats.
+    # TTL is another offer, not an idempotency conflict). So is the count of memory events the
+    # ledger holds: once an offer (or a checkpoint) is recorded that count grows, and offering
+    # again after it lapsed is a new offer — the same key would replay the first, expired
+    # answer. ONLY memory events count. The whole ledger length did, until 1.93.3: a `gate:`
+    # line from hooks/gate-observer.sh or a `record --unavailable` line between two retries
+    # made the retry a NEW offer, and Observatory replaces an unaccepted older offer with it.
     try:
-        seen = len(ledger.read_text(encoding="utf-8").splitlines())
+        seen = sum(1 for ln in ledger.read_text(encoding="utf-8").splitlines()
+                   if MEMORY_EVENT.match(ln) and not MEMORY_UNAVAILABLE.match(ln))
     except OSError:
         seen = 0
     key = hashlib.sha256(f"{state['workflowId']}\n{json.dumps(to, sort_keys=True)}\n{reason}"
@@ -318,6 +414,8 @@ def main(argv: list[str]) -> int:
     g = r.add_mutually_exclusive_group(required=True)
     g.add_argument("--answer", help="a file with the tool's JSON answer, or - for stdin")
     g.add_argument("--unavailable", help="why the tools could not be used")
+    r.add_argument("--for-run", action="store_true",
+                   help="with --unavailable: once for the whole run; silences the nudge until an answer")
     s = sub.add_parser("state", help="the workflow this run writes to; never the token")
     s.add_argument("--ledger", default=DEFAULT_LEDGER)
     h = sub.add_parser("handoff", help="observatory_handoff_create arguments: a PLANNED executor change")
@@ -346,12 +444,19 @@ def main(argv: list[str]) -> int:
     if a.cmd == "state":
         st = _load_state(ledger)
         print(json.dumps({"workflowId": st.get("workflowId"), "holdsLease": bool(st.get("leaseId")),
-                          "stale": st.get("stale")}))
+                          "stale": st.get("stale"),
+                          "memoryUnavailable": (marker_for_this_run(ledger, st) or {}).get("reason")}))
         return 0
     text = None
     if a.answer is not None:
         text = sys.stdin.read() if a.answer == "-" else pathlib.Path(a.answer).read_text(encoding="utf-8")
-    print(record(ledger, text, a.unavailable))
+    if a.for_run and a.unavailable is None:
+        p.error("--for-run goes with --unavailable")
+    try:
+        print(record(ledger, text, a.unavailable, a.for_run))
+    except UsageError as exc:
+        print(f"stage_checkpoint: {exc}", file=sys.stderr)
+        return 2
     return 0