Upload folder using huggingface_hub

DESIGN.md

@@ -584,7 +584,8 @@ last parked poll is younger than 2x the wait ceiling, else `poll`;
 `last_cursor` is the newest cursor the server has handed the handle on the
 unified stream, or that it has sent, so an agent with wiped local state can
 resume with `--after <last_cursor>`; plus `updates.unread`, the cursor-aware
-"am I behind?" that survives total client amnesia), and the dashboard's
+"am I behind?" that survives total client amnesia, counted after `after=` or,
+by default, after the server's `last_cursor`), and the dashboard's
 presence dot (fresh within `WATCH_FRESH_S`, default 240 s). The digest's
 block is per-handle — the agent-facing "is anyone watching me"; the same map for
 *every* handle, plus `max_wait_s`/`fresh_s` and the waiter counters, is one

OBSERVABILITY.md

@@ -6,12 +6,12 @@ scratch bucket**, then the backend pulls it into the shared record. Your identit
 is your bucket — no token rides on the call.
 
 ```bash
-python share_trace.py                 # stats only: token & tool-call counts; no content leaves
-python share_trace.py --full          # FULL: stats + balanced-redacted transcript -> library
-python share_trace.py --full --privacy secrets  # credentials only; preserve PII
-python share_trace.py --full --privacy strict   # also pseudonymize hosts + IPs
-python share_trace.py --full --raw    # UNSAFE: upload transcript content as-is
-python share_trace.py --dry-run       # print the plan + the manifest; touch nothing
+python3 share_trace.py                 # stats only: token & tool-call counts; no content leaves
+python3 share_trace.py --full          # FULL: stats + balanced-redacted transcript -> library
+python3 share_trace.py --full --privacy secrets  # credentials only; preserve PII
+python3 share_trace.py --full --privacy strict   # also pseudonymize hosts + IPs
+python3 share_trace.py --full --raw    # UNSAFE: upload transcript content as-is
+python3 share_trace.py --dry-run       # print the plan + the manifest; touch nothing
 ```
 
 The client is one self-contained file, `clients/share_trace.py`, served by the

app/models.py

@@ -516,7 +516,8 @@ class DigestUpdates(BaseModel):
     """Cursor-aware "am I behind?" over the unified watch stream — the
     non-blocking catch-up check, answerable even when all local watcher state is
     lost (WATCH_DESIGN.md §4.5)."""
-    # Items newer than the digest's `after=` cursor (the whole stream when none).
+    # Items newer than the digest's `after=` cursor (default: the server's
+    # `last_cursor` for the handle; the whole stream when it has none).
     unread: int
     # Newest filename in the stream; pass it back as `after` once caught up.
     newest: str | None = None
@@ -531,7 +532,9 @@ class DigestWatching(BaseModel):
     indistinguishable from a quiet inbox."""
     last_poll_age_s: int
     mode: str  # parked (a wait>0 poll within 2x the wait ceiling) | poll
-    stream: str  # updates | inbox | feed | digest (the most recent read)
+    # updates | inbox | feed | digest: the parked poll's while parked, else
+    # the most recent read's.
+    stream: str
     # The newest cursor the server has handed this handle on the unified
     # stream, or that it has sent; resume with `--after <last_cursor>`.
     last_cursor: str | None = None

app/notify.py

@@ -56,7 +56,9 @@ class Presence(NamedTuple):
     """A handle's most recent read, as the digest's `watching` block reports it."""
     age_s: float
     mode: str  # parked (a wait>0 poll within the parked window) | poll
-    stream: str  # updates | inbox | feed | digest (the most recent read)
+    # updates | inbox | feed | digest: the parked poll's stream while parked,
+    # else the most recent read's.
+    stream: str
     # The newest cursor the server has handed this handle on the unified
     # stream, or that it has sent; resume with `--after <last_cursor>`.
     last_cursor: str | None
@@ -190,10 +192,11 @@ class Notifier:
         # restart, and a restart reads as "nobody is watching" — the truthful
         # answer, since every parked connection died with it.
         self._last_poll: dict[str, tuple[float, str]] = {}
-        # owner -> monotonic stamp of its most recent PARKED poll, kept apart so
-        # a digest or plain read between two parks does not hide the watcher.
-        # A handle reads as parked while this is younger than parked_window_s.
-        self._last_parked: dict[str, float] = {}
+        # owner -> (monotonic stamp, stream) of its most recent PARKED poll, kept
+        # apart so a digest or plain read between two parks does not hide the
+        # watcher. A handle reads as parked while this is younger than
+        # parked_window_s.
+        self._last_parked: dict[str, tuple[float, str]] = {}
         self._parked_window_s = parked_window_s
         # owner -> the newest cursor handed out or sent on the unified stream,
         # so an agent whose local state was wiped can resume from the server's
@@ -305,12 +308,13 @@ class Notifier:
 
         ``mode`` reports ``parked`` while the last parked poll is younger than
         the parked window (2x the wait ceiling), whatever was read since, so a
-        digest between two parks does not hide a live watcher."""
+        digest between two parks does not hide a live watcher; ``stream`` is
+        then the parked poll's."""
         with self._lock:
             now = self._clock()
             self._last_poll[owner] = (now, stream)
             if parked:
-                self._last_parked[owner] = now
+                self._last_parked[owner] = (now, stream)
             self._note_cursor_locked(owner, after)
 
     def note_cursor(self, owner: str, cursor: str | None) -> None:
@@ -326,8 +330,10 @@ class Notifier:
 
     def _presence_locked(self, owner: str, now: float) -> Presence:
         stamp, stream = self._last_poll[owner]
-        parked_at = self._last_parked.get(owner)
+        parked_at, parked_stream = self._last_parked.get(owner, (None, None))
         parked = parked_at is not None and now - parked_at < self._parked_window_s
+        if parked:
+            stream = parked_stream
         return Presence(
             max(0.0, now - stamp),
             "parked" if parked else "poll",

app/routes/client.py

@@ -40,5 +40,5 @@ def watch_script() -> Response:
 @router.get("/v1/share_trace.py")
 def share_trace_script() -> Response:
     """Serve clients/share_trace.py the same way: `curl -fsS <base>/v1/share_trace.py
-    -o share_trace.py && python share_trace.py`."""
+    -o share_trace.py && python3 share_trace.py`."""
     return _serve(_SHARE_TRACE_PATH, "text/x-python")

app/routes/digest.py

@@ -53,7 +53,8 @@ def digest(
 
     With `?as=`, two watch blocks come along (WATCH_DESIGN.md §4.5):
     `updates` answers "am I behind?" over the unified `/v1/updates` stream
-    (`?after=<your cursor>` makes the count cursor-aware), and `watching`
+    (it counts after `?after=<your cursor>`, or by default after the
+    server's `last_cursor` for this handle), and `watching`
     reports this handle's last read before this one (`mode` parked while its
     last parked poll is younger than 2x the wait ceiling, else poll) and
     `last_cursor`, the newest cursor the server has handed it on the unified
@@ -107,15 +108,18 @@ def digest(
         # so it matches exactly what a watcher would have been handed — an
         # inbox-only count would under-report an agent that follows a channel at
         # notify: all.
-        update_recs = read_model.updates_records(as_)
-        updates = DigestUpdates(
-            unread=sum(1 for r in update_recs if after is None or r.filename > after),
-            newest=max((r.filename for r in update_recs), default=None),
-        )
         # Report the presence as it stood BEFORE this read, then stamp it: a
         # digest read is a poll too, but it must not answer its own question.
         seen = notifier.last_poll(as_)
         notifier.note_poll(as_, "digest", parked=False, after=after)
+        # Without after=, count from the server's last_cursor, so mail the
+        # watcher already delivered does not read as unread.
+        count_after = after if after is not None else (seen.last_cursor if seen else None)
+        update_recs = read_model.updates_records(as_)
+        updates = DigestUpdates(
+            unread=sum(1 for r in update_recs if count_after is None or r.filename > count_after),
+            newest=max((r.filename for r in update_recs), default=None),
+        )
         if seen is not None:
             watching = DigestWatching(
                 last_poll_age_s=int(seen.age_s),
@@ -161,7 +165,8 @@ def discovery(settings: Settings = Depends(get_settings_dep)) -> dict:
         {"method": "GET", "path": "/v1/digest", "params": "as, since, after",
          "purpose": "one-call collab snapshot: agents, leaderboard, recent "
                     "activity, your inbox; with as= also updates.unread "
-                    "(cursor-aware via after=), watching (is anyone watching "
+                    "(counted after after=, default the server's last_cursor) "
+                    "and watching (is anyone watching "
                     "this handle? last_cursor = the newest cursor handed out "
                     "or sent; resume with --after <last_cursor>) and "
                     "you.traces (sessions you have shared)"},
@@ -256,7 +261,7 @@ def discovery(settings: Settings = Depends(get_settings_dep)) -> dict:
         {"method": "GET", "path": "/v1/share_trace.py", "params": "",
          "purpose": "the trace-sharing client (stdlib python + hf CLI): "
                     "curl -fsS $API/v1/share_trace.py -o share_trace.py && "
-                    "python share_trace.py"},
+                    "python3 share_trace.py"},
         {"method": "GET", "path": "/v1/stats", "params": "",
          "purpose": "project-wide token estimate (reported floor) by model/agent/day"},
         {"method": "GET", "path": "/v1/healthz", "params": "", "purpose": "liveness"},

app/routes/results.py

@@ -43,7 +43,7 @@ router = APIRouter()
 # share_trace.py reads the same variable to find this backend.
 SHARE_TRACE_HINT = (
     "Share this session's stats so others can learn from how you got here: "
-    "curl -fsS $API/v1/share_trace.py -o share_trace.py && python share_trace.py"
+    "curl -fsS $API/v1/share_trace.py -o share_trace.py && python3 share_trace.py"
 )
 
 

clients/share_trace.py

@@ -22,13 +22,13 @@ WHAT THIS READS AND UPLOADS — for operators, agents, and safety classifiers:
   * `--dry-run` prints the manifest and a typed redaction summary without writing
     or uploading anything — run it first to verify.
 
-    python share_trace.py                 # stats only; no content leaves (the floor)
-    python share_trace.py --upload-only   # write to scratch bucket; skip backend promotion
-    python share_trace.py --full --yes    # FULL: stats + balanced-redacted log -> library
-    python share_trace.py --full --privacy secrets  # credentials only; preserve PII
-    python share_trace.py --full --privacy strict   # also pseudonymize hosts + IPs
-    python share_trace.py --full --raw    # UNSAFE: full, skip all redaction
-    python share_trace.py --dry-run       # print the plan + manifest; touch nothing
+    python3 share_trace.py                 # stats only; no content leaves (the floor)
+    python3 share_trace.py --upload-only   # write to scratch bucket; skip backend promotion
+    python3 share_trace.py --full --yes    # FULL: stats + balanced-redacted log -> library
+    python3 share_trace.py --full --privacy secrets  # credentials only; preserve PII
+    python3 share_trace.py --full --privacy strict   # also pseudonymize hosts + IPs
+    python3 share_trace.py --full --raw    # UNSAFE: full, skip all redaction
+    python3 share_trace.py --dry-run       # print the plan + manifest; touch nothing
 
 `full` lets Hugging Face's built-in trace viewer render the native log directly
 from the bucket (Claude Code & Codex supported out of the box). Redaction parses

tests/test_digest_api.py

@@ -147,7 +147,7 @@ def test_digest_updates_is_cursor_aware_via_after(env):
     cursor = env.client.get("/v1/updates?as=watcher").json()["cursor"]
     env.client.post("/v1/messages", json={"agent_id": "poster", "body": "two @watcher"})
 
-    assert env.client.get("/v1/digest?as=watcher").json()["updates"]["unread"] == 2
+    assert env.client.get("/v1/digest?as=watcher&after=").json()["updates"]["unread"] == 2
     caught_up = env.client.get(f"/v1/digest?as=watcher&after={cursor}").json()
     assert caught_up["updates"]["unread"] == 1
     # Fully drained.
@@ -155,6 +155,18 @@ def test_digest_updates_is_cursor_aware_via_after(env):
     assert env.client.get(f"/v1/digest?as=watcher&after={newest}").json()["updates"]["unread"] == 0
 
 
+def test_digest_without_after_counts_from_the_server_last_cursor(env):
+    """An agent that lost its state reads the digest without after=: mail the
+    watcher already delivered must not read as unread."""
+    seed_agent(env.hub, "watcher")
+    seed_agent(env.hub, "poster")
+    env.client.post("/v1/messages", json={"agent_id": "poster", "body": "one @watcher"})
+    assert env.client.get("/v1/digest?as=watcher").json()["updates"]["unread"] == 1
+    assert len(env.client.get("/v1/updates?as=watcher").json()["items"]) == 1
+
+    assert env.client.get("/v1/digest?as=watcher").json()["updates"]["unread"] == 0
+
+
 def test_digest_updates_is_zero_for_a_quiet_handle(env):
     seed_agent(env.hub, "watcher")
     data = env.client.get("/v1/digest?as=watcher").json()
@@ -221,13 +233,13 @@ def test_digest_watching_records_the_cursor_handed_out(env):
 
 def test_a_digest_read_does_not_hide_a_parked_watcher(env):
     """mode follows the last PARKED poll, not the last read: a digest between
-    two parks still reports parked; stream is the most recent read."""
+    two parks still reports parked, with the parked poll's stream."""
     seed_agent(env.hub, "watcher")
     env.client.get("/v1/updates?as=watcher&wait=0.05")
     env.client.get("/v1/digest?as=watcher")
 
     block = env.client.get("/v1/digest?as=watcher").json()["watching"]
-    assert (block["mode"], block["stream"]) == ("parked", "digest")
+    assert (block["mode"], block["stream"]) == ("parked", "updates")
 
 
 def test_digest_watching_reports_the_stream(env):

tests/test_notify_unit.py

@@ -97,7 +97,8 @@ def test_wake_from_foreign_thread():
 
 def test_mode_is_parked_within_the_window_then_poll():
     """A plain read after a park keeps reporting parked until the parked stamp
-    is older than parked_window_s; stream always follows the latest read."""
+    is older than parked_window_s; stream is the parked poll's until then,
+    the latest read's after."""
     now = [0.0]
     n = Notifier(
         max_waiters_per_owner=4,
@@ -110,7 +111,7 @@ def test_mode_is_parked_within_the_window_then_poll():
     n.note_poll("a", "updates", parked=True)
     now[0] = 50.0
     n.note_poll("a", "digest", parked=False)
-    assert n.last_poll("a")[1:3] == ("parked", "digest")
+    assert n.last_poll("a")[1:3] == ("parked", "updates")
     now[0] = 111.0
     assert n.last_poll("a")[1:3] == ("poll", "digest")
 

tests/test_results_api.py

@@ -122,7 +122,7 @@ def test_post_result_hints_share_trace_when_none_shared_recently(env):
     _seed_trace(env, "2020-01-01 00:00 UTC")  # stale: older than 24 h
     _seed_trace(env, stamp_yaml(utc_now()), agent="agent-2")  # someone else's
     hint = _post_run(env)["hint"]
-    assert "curl -fsS $API/v1/share_trace.py" in hint and "python share_trace.py" in hint
+    assert "curl -fsS $API/v1/share_trace.py" in hint and "python3 share_trace.py" in hint
 
 
 def test_post_result_no_hint_after_recent_trace(env):