taskops-cli 0.5.8__tar.gz → 0.6.1__tar.gz

{taskops_cli-0.5.8 → taskops_cli-0.6.1}/ARCHITECTURE.md

@@ -3112,3 +3112,104 @@ or highlight.js with the eleven grammars): keyword, string, comment, number,
 tag, attribute — enough to read by, in six `--code-*` tokens that live in
 `theme/tokens.css` beside the palette rather than borrowing its status colours.
 The bundle grew 288 307 → 313 294 bytes for the whole feature.
+
+## 23. The Stream — the log beside the code, live (2026-09-08)
+
+Berna asked for "un streaming de comentarios en tiempo real … cada progress,
+cada comment, se muestra, se highlitean los nuevos, se puede ver el card tipo
+popup … al lado del editor … con una excelente organización y agrupación". It
+is a third column inside the Editor (`ui/src/components/stream/`), shut by
+default, opened from the one bar that page has.
+
+**The socket did not change, and that is the whole design.** `http/feed.py`
+publishes `{"type":"change","verb","seq"}` and nothing else, because that is
+what lets a PUBLIC board's feed open with no credential: a watcher learns only
+THAT the board moved and re-reads through `/rpc`, where the anonymous gate
+applies again in full. A live comment column is exactly the feature that would
+have tempted a payload onto that frame, and the day a message carries a card
+that door has to close with it. So: the socket pokes, the page reads.
+
+**What DID change is the direction the log can be read in.** `events` used to
+answer backwards only — newest-first pages on a `before=` cursor — so "what
+arrived since I looked" was a thing the client had to DERIVE: `head - lastHead`
+rows off page one, plus a set of already-seen ids as the safety net for a burst
+larger than a page (`ui/src/components/toasts/model.ts` is the post-mortem of
+that arithmetic, and it is exact only until it is not).
+
+```
+events                        → the newest page          next = the older cursor
+events before=<seq>           → further back             next = the older cursor
+events after=<seq>            → what arrived since,      next = carry on from here
+                                OLDEST first                   (a full page means more)
+```
+
+`next` means the same thing in both directions — the cursor for the page you
+have not read yet, in the direction you are reading — and the two cannot be
+asked at once, which is two questions and is refused as one. The SQL is
+`store/cache.py::since`, which replay already used, given a `limit`: a
+catch-up is capped on the OLDEST end, which is the one thing a descending
+`page()` cannot do.
+
+**The cursor a live reader carries is `head`, not a seq per row.** The rowid is
+still dropped on the way out (`verbs/events.py:53` was and remains the shape).
+A reader keeps the `head` of the answer it read and asks `after=<that head>`;
+what comes back IS the news, by construction — no arithmetic, no dedupe, and no
+way to be wrong when six hundred events landed while the tab was asleep, because
+then it pages forward on `next` and, past `CATCH_UP_PAGES`, starts over on page
+one rather than drawing a list with a hole in the middle.
+
+**Still ONE read of the log.** `useEvents` is called in `App`, once, and three
+surfaces are handed the result — the Monitor's Event stream, the comment toasts,
+and this rail. The change is that it CATCHES UP instead of starting over: new
+rows are prepended, the reader's scrollback survives, and a quiet board answers
+with an empty list instead of fifty rows on every poke.
+
+**What arrived is stamped in the CLIENT's clock**, never in `Event.ts`. A
+comment written three minutes ago that reaches this tab now is new HERE, and a
+rail that highlighted by `ts` would show it already faded — `toasts/model.ts::
+Toast.shown` decided the same thing first, for the same reason. The stamps are
+pruned to a minute, so the map is bounded by what arrived, not by how long the
+tab has been open. Nothing is stored: there are no read-receipts on this board
+and there is no mark-as-read verb, by design (§11), so "new" is arithmetic that
+dies with the tab.
+
+**The organisation is a MOMENT, not a row.** The Monitor's pane draws one row
+per event and is right to: it answers "what happened, in order, ever". A 320px
+column beside the code answers "what are the workers doing right now", and at
+that question one row per event is noise — a `taskops_plan` of nine cards is
+nine identical rows. So consecutive events by the same actor on the same card
+within `MOMENT_GAP_S` (120s) fold into one entry, counted, sized and ended with
+the worker's own number: `2 commits · 2 files · +41 −7 · progress → 68`. The
+fold is on (actor, task) because a worker moving between cards is the change a
+reader wants to see, and it is CONSECUTIVE-only, so an entry can never be
+hoisted above events that happened after it. Files are counted per PATH across
+the run — one file touched in three commits is one file — through
+`Thread.tsx::changed`, which is the Event stream's own numstat fold given a
+list; a second definition of "how much changed" is the drift `format.ts` is the
+post-mortem of.
+
+**Three ways to narrow, none of them a fetch:** five families (`talk` `work`
+`code` `review` `chapter`, every kind in `core/kinds.py` in exactly one), one
+card followed by clicking its id, and `older` for history. `progress` needs no
+branch anywhere — it is an `edited` event (`verbs/update.py::_progress` argues
+why it is not a kind of its own) and the roll-up reads it off the body.
+
+**The reader's place is never taken.** New entries land on top; a reader who has
+scrolled down into history does not have the list move under them, and a pill
+says how many are waiting above. The card popup is `openCard` — App's one door
+into the Drawer, which is mounted once over whichever page is on — so the rail
+draws no dossier of its own and the same card opens identically from the Board,
+the Monitor and here.
+
+**What the headless harness does and does not pin**
+(`ui/smoke/sections/stream-rail.tsx`): the fold, the roll-up, the numstat, the
+freshness tiers, the merge, the arrival stamps, the narrowing, the entry markup,
+the three empty states and the Editor's third column — all pure functions or
+`Stream`, which renders under `react-dom/server` with no client, no socket and
+no timer. Not pinned, and said rather than faked with a jsdom: the scroll
+position, the one interval, and the catch-up walk. The `after=` half is pinned
+on the server, where it is decided (`tests/test_verbs.py`), including the
+burst-larger-than-a-page case the client arithmetic could not survive.
+
+The bundle grew 330 231 → 341 411 bytes for the whole feature: the model, the
+rail and the Editor's third column, no dependency added.

{taskops_cli-0.5.8 → taskops_cli-0.6.1}/CHANGELOG.md

@@ -3,6 +3,72 @@
 The source of truth for release notes — GitHub Releases are extracted from
 here, never written twice.
 
+## 0.6.1 — the Stream earns its column
+
+- **Open the files the agents name.** Every entry now wears the paths it
+  named, and a click opens that file in the editor beside it — switching to
+  the card's own worktree when it has one on this disk. Three sources, in
+  descending order of trust: a commit's `numstat` keys (git's own answer), a
+  created card's declared `files`, and what the prose names.
+- **The prose half is a guess and is kept one.** Agents write paths to each
+  other constantly — "the fix site is `verbs/_facts.py::pending_mentions`" —
+  and no structured field carries them. So they are extracted, narrowly:
+  backticked or bare, a trailing `::symbol` / `:line` / `:line:col` stripped
+  because `events.py:53` names a file and not a file with that name, never a
+  URL, never a bare directory, capped. A false negative costs a click; a false
+  positive is the rail lying about the disk.
+- **Markdown**, the drawer's own renderer over the same parser, so a fence, a
+  list and a `path` read here exactly as they read there. The 96-character cut
+  is gone: it landed inside a fence as often as not, and what the reader saw
+  was not a shortened comment but a broken one. The clamp is now a HEIGHT,
+  undone by expanding the entry — and expansion is a set, not a flag, because
+  a reader opens two comments to compare them as often as one.
+- **The rail resizes by hand**: a grip on its edge, 240–760px, double-click to
+  reset, and the width is remembered across leaving the tab. The listeners are
+  on the document and not the handle — bound to a 6px strip they are lost the
+  first time the pointer outruns the render.
+- `useStream` is the container half, extracted so a second mount of the same
+  picture cannot come to disagree about what is new or which family is on.
+- Four mutations, one site at a time. Two assertions were born FALSE and found
+  by running them: a path cleaner that did not strip backticks, and a "draws
+  no chips" claim asserted against a mount that HAD an editor.
+- The bundle grew 341 411 → 345 368 bytes.
+
+## 0.6.0 — the Stream, beside the code
+
+- **A live rail inside the Editor**: every comment, every commit, every
+  `progress` a worker reports, as it happens, in a third column you open from
+  the page's one bar. Shut by default — the Editor's whole decision is that the
+  code gets the window, and a live column appearing unasked would be that
+  decision taken back on the reader's behalf.
+- **The socket did not change.** A frame is still `{"type":"change","verb","seq"}`
+  and nothing else, which is what lets a public board's feed open with no
+  credential. The socket pokes; the page reads.
+- **`events` can be read forwards**: `after=<seq>` answers exactly the rows
+  written since the cursor a reader already holds, oldest first, and pages
+  forward on `next` when the catch-up is bigger than one page. The cursor is
+  `head` — the rowid is still not sent per row. What that replaces is the
+  arithmetic the client had to do over page one (`head - lastHead` rows plus a
+  seen-set), which was exact only until a burst was larger than a page.
+- **The one log read catches up instead of starting over.** New rows are
+  prepended, so a reader's scrollback survives a board that is moving, and a
+  quiet board answers with an empty list instead of fifty rows on every poke.
+  Three surfaces still share one read: the Monitor's pane, the toasts, the rail.
+- **A run of work is one entry.** Consecutive events by one worker on one card
+  within two minutes fold together, counted and sized:
+  `2 commits · 2 files · +41 −7 · progress → 68`. Nine rows from one
+  `taskops_plan` were the shape this exists to stop drawing.
+- **What arrived is marked and fades by arithmetic** — stamped in the reader's
+  own clock, never the event's, so a comment that reaches the tab late is new
+  HERE. Nothing is stored: no badge, no counter, no read-receipt.
+- **The reader's place is never taken**: entries land on top, a reader scrolled
+  into history is not moved, and a pill says how many are waiting above.
+- Filter by family (talk · work · code · review · chapter), follow one card by
+  clicking its id, open its dossier in the popup every other view uses.
+- Five mutations, one site at a time, and one of them found a fixture that was
+  not exercising the rule it claimed to pin.
+- The bundle grew 330 231 → 341 411 bytes. No dependency added.
+
 ## 0.5.8 — the Editor is the whole window
 
 - **Nothing is drawn above the Editor any more** — no KPI rail, no header, no

{taskops_cli-0.5.8 → taskops_cli-0.6.1}/CLAUDE.md

@@ -270,6 +270,12 @@ what it exists to report, not a fault.
   cannot conflict.
 - **Do not run browser/UI demos unless asked.** The UI is tested headlessly
   through `react-dom/server`, no browser and no jsdom.
+- **The Editor carries the Stream rail** — the log, live, in a third column,
+  shut by default (ARCHITECTURE §23). It fetches NOTHING: `useEvents` is read
+  once in `App` and three surfaces share it, and the socket frame is still a
+  signal, never a payload. A run of events by one worker on one card inside two
+  minutes is ONE entry; "new" is stamped in the reader's clock and fades by
+  arithmetic, because there is no mark-as-read verb and never will be.
 - One card rebuilds the bundle at the end of a wave. N cards rebuilding it is
   N-1 conflicts by construction.
 

{taskops_cli-0.5.8 → taskops_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskops-cli
-Version: 0.5.8
+Version: 0.6.1
 Summary: A shared work board for teams of coding agents, with a human who decides.
 Project-URL: Repository, https://github.com/bernatch22/taskops
 License-Expression: MIT

{taskops_cli-0.5.8 → taskops_cli-0.6.1}/src/taskops/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
 __title__ = "taskops"
-__version__ = "0.5.8"  # single source of truth; pyproject reads it dynamically
+__version__ = "0.6.1"  # single source of truth; pyproject reads it dynamically

{taskops_cli-0.5.8 → taskops_cli-0.6.1}/src/taskops/store/cache.py

@@ -93,8 +93,19 @@ class Cache:
         rows = self._query("SELECT kind, COUNT(*) FROM events GROUP BY kind")
         return {str(kind): int(n) for kind, n in rows}
 
-    def since(self, seq: int) -> list[tuple[int, Event]]:
-        return self._events("WHERE seq > ? ORDER BY seq", (seq,))
+    def since(self, seq: int, limit: int | None = None) -> list[tuple[int, Event]]:
+        """Everything after `seq`, OLDEST first — replay's order, and the order
+        a live reader catches up in.
+
+        `limit` is for the second caller only (`verbs/events.py`'s `after=`): a
+        page of a CATCH-UP is read forwards, so the cap has to fall on the
+        oldest end and not on the newest, which is the one thing a descending
+        `page()` cannot do. Replay passes nothing and reads the tail whole —
+        that is what makes a cache rebuildable.
+        """
+        if limit is None:
+            return self._events("WHERE seq > ? ORDER BY seq", (seq,))
+        return self._events("WHERE seq > ? ORDER BY seq LIMIT ?", (seq, limit))
 
     def page(self, before: int | None, limit: int) -> list[tuple[int, Event]]:
         """One page of the whole log, NEWEST FIRST, by keyset on `seq`.