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

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

@@ -107,6 +107,7 @@ erDiagram
         list files "edit surface, a hint, never a lock"
         list labels
         string assignee "who it is FOR — not a claim"
+        int progress "0-100, the worker's own REPORT — absent until one is made"
         string created_by
         float created
         float updated "replay arbiter, newer-wins"
@@ -183,6 +184,18 @@ turns it on derives exactly as it did before the feature existed
 (`tests/test_core.py::test_a_card_without_review_derives_exactly_as_before`). There is deliberately no path in
 this diagram labelled "recover": nothing is ever wrong for a recover to fix.
 
+`progress` (0–100) is the one field that is neither: STORED, like the three
+statuses, and yet no state at all — nothing derives from it, nothing gates on
+it, `done` does not write 100, and a card nobody has reported on has no key
+rather than a zero. It is a worker's own sentence about its own card
+(`verbs/update.py::_progress`), written with `taskops_update progress=` every
+5–10 points, guarded exactly as a release is (yours, and never a stranger's).
+It is not a derived state because deriving it would mean the board guessing how
+far along somebody is; it is not a lifecycle status because nothing may ever
+branch on it. What it buys beyond the number is the heartbeat: the write is MCP
+traffic, and MCP traffic is the lease's only proof of life (§12), so a worker
+that reports is a worker that cannot read as `stalled` while it is reporting.
+
 One more fact is derived the same way and is about a *reader*, not a card: a
 **pending mention** (`core/mentions.py`). Being named in a comment's optional
 `mentions[]` is pending until that actor writes any event on the card, or the
@@ -3042,3 +3055,60 @@ many slots and Actors anchors on a calendar month, so one number cannot be both,
 and moving between those tabs costs one request. A board one version behind
 sends no `window` key at all, and `windowSaid()` falls back to the day-bucket
 sentence — a degradation, never a blank.
+
+---
+
+## 22. The Editor — a worktree's files, live off the disk (2026-09-06)
+
+Berna asked for "an editor inside taskops: the worktrees, a sidebar with the
+file directory, the code on the right in tabs, highlighted — the real code of
+each worktree in real time, from local". It is the sixth tab
+(`ui/src/pages/Editor.tsx`), read-only by construction, and it answers the one
+question the Worktrees page cannot: not what a branch ADDS as a patch, but what
+the code LOOKS LIKE right now in the directory a worker is sitting in.
+
+**The contract** (`http/editor.py`, same envelope and same token door as `/git`):
+
+```
+GET /<board>/editor/trees                      every inhabited directory, the checkout (`main`) first
+GET /<board>/editor/tree?tree=<name>           files: path, size, mtime, git state · capped, total, cap, seq
+GET /<board>/editor/file?tree=&path=[&base=]   text or binary, truncated+cap, tracked, base {ref, sha}, marks [[from,to,kind]]
+GET /<board>/editor/diff?tree=&path=[&base=]   the same file as a unified patch — the Worktrees page's own renderer draws it
+GET /<board>/editor/feed?tree=<name>           WebSocket/SSE: {"type":"change","tree","seq"} — a SIGNAL, never the files
+```
+
+**Only a WINDOW answers.** The files live on the disk `taskops ui` runs on; a
+serve-mode host (taskops.bernardocastro.dev) holds boards and at most a bare
+`repo.git`, so it refuses with ONE sentence naming `taskops ui`
+(`editor.NO_CHECKOUT`) and the page quotes it — never an empty tree.
+
+**The security line** is `gitwork/inhabited.py`, three sentences: a tree is a
+directory NAME matched before it is joined to anything; a file is resolved on
+both ends and refused — never repaired — when it leaves the tree, names `.git`,
+or is a symlink out; and a base ref passes `diff.usable`, the wall every ref of
+the /git door passes. `tests/test_editor.py` drives every shape through the door.
+
+**Live, without a watcher dependency** (§11 stands): `gitwork/scan.py` lists a
+tree with git (index + untracked walk honouring every `.gitignore`, the
+directories nobody reads pruned at the directory) and measures it with one
+`stat` per file; `http/treewatch.py` runs that once a second for a tree
+somebody is listening to — `watcher.py`'s lifetime rule — and publishes when
+two scans differ. The page re-reads the listing on a signal and re-reads only
+the open tabs whose mtime moved, lighting the lines `changedSpan` names and
+keeping the scroll (`components/editor/useWorktree.ts`). Measured on a
+worker's tree in pinecall/v2: a new file in the tree 0.8 s after the write, an
+open tab re-rendered 0.2 s after it.
+
+**The caps, all stated in the answer:** `scan.FILE_CAP` = 4000 files per tree
+(`capped` + `total` beside the list), `reading.CAP` = `patch.CAP` = 512 KiB per
+file and per patch (`truncated` + `cap`), binary decided on the first 8 KiB
+(a NUL or non-UTF-8) and never decoded. The gutter's base is the card's own
+chapter branch through `diff.compare_range` — the merge-base in flight, the
+fork point once integrated — and `HEAD` for the checkout.
+
+**Highlighting is a compact tokenizer, not a dependency**
+(`components/editor/highlight.ts`, ~4 kB minified against ~25–45 kB for Prism
+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.

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

@@ -3,6 +3,85 @@
 The source of truth for release notes — GitHub Releases are extracted from
 here, never written twice.
 
+## 0.5.8 — the Editor is the whole window
+
+- **Nothing is drawn above the Editor any more** — no KPI rail, no header, no
+  tab bar. It was a card on a canvas while also being the only view that wants
+  the entire screen, and the cost was visible: a rounded top edge under a bar
+  with nothing above it, 24px of canvas down both flanks of a file tree, and a
+  bottom edge that read as a scroll that was not there. Padding zero, radius
+  zero, no outer border: the panel IS the window. It had shrunk to a small bar
+  before, and a small bar is still a lid.
+- **One thin bar inside the page** carries the way out, which tree is open and
+  what the door said about it. It sits outside the panel deliberately: the
+  refusal and the loading states replace the panel whole, and the exit must not
+  go with it. The exit is an arrow — a glyph in a bar of monospace facts, with
+  its words in `aria-label` and `title` so nothing is lost to a reader who
+  cannot see it — and `onBack` is REQUIRED by the page's props, because this is
+  the one view with no tab bar and a caller must not be able to strand somebody
+  on it by omission.
+- **`Header.compact` is deleted**: a second shape of that component nothing
+  could reach any more, still asking to be kept in step.
+- Four assertions pin the new geometry and each was measured red at its own
+  site. One of them was born FALSE and is fixed here — it read the `style`
+  attribute with the pattern's attribute order backwards, matched nothing, and
+  `undefined !== true` passed with the padding put straight back. It now has to
+  FIND the node before it says anything about it, and that blind spot is
+  mutated red too.
+
+## 0.5.7 — the Editor, and a card that says how far along it is
+
+- **A card reports its own progress** — `taskops_update progress=0-100`, an
+  argument on the verb that already changes the card and deliberately not a
+  twelfth tool. Stored as an `edited` event, so the log, the fold and the
+  thread renderer read it with no new kind and no new replay rule. A REPORT and
+  never a state (ARCHITECTURE §3): nothing derives from it, nothing gates on
+  it, `done` does not write 100, and a card nobody has spoken about carries NO
+  key rather than a zero — the tile draws a bar only once somebody has spoken.
+  Guarded exactly as a release is: yours, never a stranger's, refused on a
+  closed card, and backwards is allowed because a task that turned out bigger
+  is honest. The cadence rides where a worker actually reads it — the assign
+  brief, the take's footer and the MCP protocol text — and the write doubles as
+  the lease's heartbeat, so a worker that reports cannot read as STALLED while
+  it is reporting. On screen: a track and its number in the tile, one pill in
+  the drawer, `· 35%` on the board's text line.
+- **The board stopped going grey when you switch chapter.** Every tile arrived
+  inverted and the play that reveals them never ran, so the columns drew their
+  counts over nothing. Three defects, each found only after the one above it
+  was fixed: a cancelled play was dropped with its styles instead of being
+  played; rects were measured WITH the animation's own transforms, so the
+  offsets cascaded (6px → -12px → -6.66px → 12.99px); and the release looked
+  ids up in a ref map React had already emptied, since children detach in the
+  mutation phase before a parent's cleanup runs. All three now decided in
+  `components/board/flip.ts`, where a headless test can reach them, and
+  verified in a browser on the only shape that reproduces it — two chapters
+  that both have tiles: 0 stuck rounds of 6, where the same probe read 5 of 6.
+
+- **A sixth tab, Editor** (`ui/src/pages/Editor.tsx`): pick a worktree — the
+  checkout first, then every directory under `.taskops/trees/` — and read its
+  files as an editor draws them: a folder tree on the left with each file's git
+  state (M/A/S/U) and a dot on every folder something moved under, tabs on the
+  right, line numbers, syntax colour for Python, TS/JS, JSON, YAML, TOML,
+  Markdown, SQL, bash, HTML and CSS, a gutter mark on every line that changed
+  since the branch base, and a per-file "diff vs base" toggle through the same
+  patch renderer the Worktrees page uses. Read-only, always.
+- **Live from local disk**: a tree somebody is looking at is scanned once a
+  second (git for the listing, `stat` for the measure — no watcher dependency),
+  the page re-reads only the open tabs that moved, lights the changed lines and
+  keeps the scroll; a "last change: <file> · <ago>" line says the project is
+  moving. Doors in from every worktree row, the diff page and the dossier.
+- **The tree folds to the working set** — what the branch wrote since its
+  base (`committed`, `deleted`, one `git diff --name-status` per scan) plus
+  the dirt — every other folder closed; ⌘P/Ctrl+P quick open with VS Code's
+  fuzzy rule (one definition, also the tree's filter); an Explorer-shaped
+  sidebar with keyboard navigation, file icons from one inline sprite, a tab
+  strip that scrolls on its own axis, and the whole page at viewport height.
+- **`GET /<board>/editor/{trees,tree,file,diff,feed}`** (`http/editor.py`),
+  same token door and envelope as `/git`, served ONLY by a window — the
+  deployed host says so in one sentence. Files come only from inside the
+  board's own worktrees; `..`, absolute paths, `.git` and symlinks out are
+  refused. Caps stated in every answer. ARCHITECTURE.md §22.
+
 ## 0.5.6 — the hours page draws every hour of a day that opened before midnight
 
 Reported live on `/convo/`: the hours breakdown was empty. Monday said

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskops-cli
-Version: 0.5.6
+Version: 0.5.8
 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
@@ -412,7 +412,8 @@ taskops_merge      integrate DONE cards into the milestone branch (--no-ff);
                    milestone= lands a finished chapter. main is never touched
 taskops_take       claim your card and get everything back
 taskops_update     change the CARD: close, hand in for review, hand back, drop,
-                   retitle, re-spec, re-prioritise, declare a dependency
+                   report progress (progress=0-100, every 5-10 points as you
+                   work), retitle, re-spec, re-prioritise, declare a dependency
 taskops_review     the verifier's one door: claim a submitted card, then
                    verdict=pass|changes note=…
 taskops_comment    say something on ANY card, including one somebody else holds

{taskops_cli-0.5.6 → taskops_cli-0.5.8}/README.md

@@ -400,7 +400,8 @@ taskops_merge      integrate DONE cards into the milestone branch (--no-ff);
                    milestone= lands a finished chapter. main is never touched
 taskops_take       claim your card and get everything back
 taskops_update     change the CARD: close, hand in for review, hand back, drop,
-                   retitle, re-spec, re-prioritise, declare a dependency
+                   report progress (progress=0-100, every 5-10 points as you
+                   work), retitle, re-spec, re-prioritise, declare a dependency
 taskops_review     the verifier's one door: claim a submitted card, then
                    verdict=pass|changes note=…
 taskops_comment    say something on ANY card, including one somebody else holds

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

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

{taskops_cli-0.5.6 → taskops_cli-0.5.8}/src/taskops/core/machine.py

@@ -111,6 +111,20 @@ def check_release(card: Card, facts: Facts, actor: str, note: str) -> None:
         )
 
 
+def check_progress(card: Card, facts: Facts, actor: str) -> None:
+    """A percentage is the worker's own report, so it is the worker's to write.
+
+    The same wall as closing and releasing (`_not_somebody_elses`): a lapsed
+    lease does not cost you your own card, a live holder who is somebody else
+    does. Nothing else is judged — not the direction (40 after 60 is honest when
+    the task turned out bigger) and not the step, because a guard on either
+    would only teach a worker to lie in fives.
+    """
+    if facts.status in CLOSED:
+        raise Refused(f"{card['id']} is {facts.status}; there is no progress left to report")
+    _not_somebody_elses(card, facts, actor)
+
+
 def _not_somebody_elses(card: Card, facts: Facts, actor: str) -> None:
     """A lease that lapsed does NOT cost you your own card.
 

{taskops_cli-0.5.6 → taskops_cli-0.5.8}/src/taskops/core/types.py

@@ -85,6 +85,10 @@ class Card(TypedDict):
     files: list[str]  # the edit surface as the planner understands it — a hint, never a lock
     labels: list[str]  # routing and search; anybody may edit them
     assignee: str  # "" is the open pool; dispatch writes it. NOT a claim — the lease is.
+    progress: NotRequired[int]
+    """0–100, the worker's own estimate, written by `taskops_update progress=`
+    and absent until the first report. A REPORT, never a state: nothing derives
+    from it and nothing gates on it (`verbs/update.py::_progress` argues it)."""
     created_by: str
     created: float
     updated: float  # the replay arbiter (newer-wins)
@@ -189,5 +193,6 @@ EDITABLE = (
     "labels",
     "assignee",
     "review",
+    "progress",
 )
 LIST_FIELDS = ("after", "files", "labels", "criteria")  # edited as a whole list, never appended to

taskops_cli-0.5.8/src/taskops/gitwork/inhabited.py

@@ -0,0 +1,105 @@
+"""The inhabited directories of a checkout — the main worktree and every tree
+under `.taskops/trees` — named, found, and walled.
+
+`trees.py` is the GEOMETRY (where a card's directory goes, how it is cut);
+this is the READ of that geometry for a screen: which directories exist right
+now, and whether a path a browser sent stays inside one of them. The Editor
+(ARCHITECTURE.md §22) shows the real files of a real worktree, so the walls
+here are the whole of its security posture, in three sentences:
+
+* A tree is addressed by its DIRECTORY NAME under `.taskops/trees/` — `tk-…`,
+  `_ms-…` — or by `main`, the checkout itself. `NAME` admits no slash and no
+  `..`, so a name never becomes a path before `locate()` has joined it to the
+  one directory it may name.
+* A file is addressed by a plain repo-relative path, and `inside()` decides by
+  RESOLVING both ends: the real path of the file must sit under the real path
+  of the tree. A `..`, an absolute path, a doubled slash, a NUL, or a symlink
+  that leaves the tree all collapse to the same answer, `None` — a path is
+  refused, never repaired.
+* `.git` is never a file of the project. In a linked worktree it is a FILE
+  pointing at the common dir, and the common dir holds every branch's objects
+  and the hooks; in the checkout it is the directory itself. Neither is code.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+from pathlib import Path
+
+from . import run
+from .trees import trees_dir
+
+MAIN = "main"
+"""The checkout itself, listed first: the one directory that is not a card."""
+
+NAME = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]{0,80}$")
+"""A tree's name — one directory name, never a path. `..` cannot match it."""
+
+
+class Tree(NamedTuple):
+    name: str
+    path: Path
+    dir: str  # repo-relative: "" for the checkout, `.taskops/trees/<name>` otherwise
+    branch: str  # "" on a detached HEAD
+    head: str  # the commit checked out, 40-hex, "" when git could not say
+
+
+def listed(repo: Path) -> list[Tree]:
+    """Every inhabited directory, the checkout first and the trees in name order.
+
+    A directory under `trees/` with no `.git` in it is not a worktree — a stray
+    folder, a removed tree git has not pruned — and is left out rather than
+    shown as one: a tree on this screen is a place a worker can be."""
+    found = [describe(MAIN, repo, "")]
+    root = trees_dir(repo)
+    if root.is_dir():
+        for path in sorted(root.iterdir()):
+            if path.is_dir() and (path / ".git").exists():
+                found.append(describe(path.name, path, str(path.relative_to(repo))))
+    return found
+
+
+def locate(repo: Path, name: str) -> Path | None:
+    """The directory `name` addresses, or None — the ONLY door from a string to
+    a tree. The name is matched BEFORE it is joined to anything."""
+    if name == MAIN:
+        return repo
+    if not NAME.match(name):
+        return None
+    path = trees_dir(repo) / name
+    return path if path.is_dir() and (path / ".git").exists() else None
+
+
+def inside(tree: Path, rel: str) -> Path | None:
+    """The real file `rel` names inside `tree`, or None.
+
+    Resolved on both ends, so a symlink that points outside the tree is caught
+    by the same comparison that catches `..` — there is one wall, not a list of
+    shapes to recognise. A path that resolves to the tree itself is refused
+    too: the door reads FILES."""
+    if not rel or rel.startswith(("/", "\\")) or "\\" in rel or any(ord(c) < 32 for c in rel):
+        return None
+    parts = rel.split("/")
+    if any(part in ("", ".", "..", ".git") for part in parts):
+        return None
+    base = tree.resolve()
+    try:
+        target = (tree / rel).resolve(strict=True)
+    except OSError:
+        return None
+    if base not in target.parents:
+        return None
+    return target if target.is_file() else None
+
+
+def describe(name: str, path: Path, rel: str) -> Tree:
+    """One inhabited directory, as the screen names it: two git questions."""
+    head = run.git("rev-parse", "--verify", "--quiet", "HEAD", cwd=path)
+    return Tree(
+        name=name,
+        path=path,
+        dir=rel,
+        branch=run.branch_at(path),
+        head=head.out.strip() if head.ok else "",
+    )

taskops_cli-0.5.8/src/taskops/gitwork/reading.py

@@ -0,0 +1,165 @@
+"""One file of a worktree, read for the screen: text or "binary", capped, and
+the lines that moved since the branch base — as gutter marks, or as a patch.
+
+The WORKING COPY is the subject, not a commit: the Editor (ARCHITECTURE.md §22)
+shows what a worker's directory holds right now, saved and unsaved-to-git
+alike, which is exactly what `patch.show` (a committed file at a sha) cannot
+say. So the bytes come off the disk, and "what changed" is `git diff <base> --
+<path>` run INSIDE the tree, which git reads as "this commit against the
+working copy as the index sees it". An untracked file is not in the index and
+that diff is empty for it; `--no-index` against `/dev/null` is what git itself
+offers for "a file that is all addition", and it is the one exception spelled
+out here rather than a synthetic patch assembled by hand.
+
+The BASE is a merge-base, never the ref itself, for the reason `diff.py`
+argues at length: a card's chapter has moved on since the card branched, and
+diffing against its tip would draw every sibling's work as this file's
+change. No ref given means HEAD — "what did this directory change since its
+last commit" — which is the right question for the checkout itself.
+
+The file cap is `patch.CAP`, the one number every capped answer in this
+package states, and a cut file SAYS it was cut. Binary is decided on the
+first `PROBE` bytes: a NUL, or bytes that are not UTF-8, and the answer is
+"binary, N bytes" with no text at all — never a screen of replacement glyphs.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+from pathlib import Path
+
+from . import run, diff, patch
+
+CAP = patch.CAP
+PROBE = 8192
+
+HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+"""A hunk header: only the NEW side's start is read — every mark is a fact
+about the file on screen — and the counts come from the body, because with
+zero context git folds a changed line and the lines added right after it into
+ONE hunk, and the header's two counts cannot say which is which."""
+
+ADDED, MODIFIED, DELETED = "added", "modified", "deleted"
+
+
+class Read(NamedTuple):
+    text: str
+    binary: bool
+    truncated: bool
+    size: int
+    mtime: float
+
+
+class Base(NamedTuple):
+    ref: str  # what was asked for: a branch name, or HEAD
+    sha: str  # what was diffed against: the merge-base, 40-hex
+
+
+class Mark(NamedTuple):
+    start: int  # 1-based, inclusive, on the file as it stands
+    end: int
+    kind: str  # ADDED | MODIFIED | DELETED (something was removed after `start`)
+
+
+def read(path: Path, cap: int = CAP) -> Read:
+    """The bytes on disk, decided text or binary and capped. `path` has passed
+    `inhabited.inside` — this function trusts it and resolves nothing."""
+    found = path.stat()
+    with path.open("rb") as handle:
+        head = handle.read(cap + 1)
+    if _binary(head[:PROBE]):
+        return Read("", True, False, found.st_size, found.st_mtime)
+    cut = len(head) > cap
+    text = head[:cap].decode("utf-8", "ignore") if cut else head.decode("utf-8", "replace")
+    return Read(text, False, cut, found.st_size, found.st_mtime)
+
+
+def base_of(tree: Path, ref: str) -> Base | None:
+    """The commit the working copy is compared against, or None when `ref`
+    names nothing this tree can see.
+
+    `diff.compare_range(ref, HEAD)` is the whole arithmetic, REUSED: the
+    merge-base while the card is in flight, and — once the card is integrated
+    and its tip is an ancestor of the chapter — the point it forked from, read
+    off the merge that brought it in. Seen live on a card the orchestrator had
+    just merged: `merge-base(ms/…, HEAD)` was HEAD itself, and every line the
+    card wrote read as unchanged. Both names pass `diff.resolve` inside it, the
+    package's one door from a string to a sha."""
+    if not ref:
+        head = diff.resolve(tree, "HEAD")
+        return Base("HEAD", head) if head else None
+    found = diff.compare_range(tree, ref, "HEAD")
+    return Base(ref, found[0]) if found else None
+
+
+def tracked(tree: Path, rel: str) -> bool:
+    """Is this path in the index? `--error-unmatch` makes git say so by exit
+    code, which is the whole answer."""
+    return run.git("ls-files", "--error-unmatch", "--", rel, cwd=tree).ok
+
+
+def marks(tree: Path, sha: str, rel: str, *, is_tracked: bool, lines: int) -> list[Mark]:
+    """Which lines of the file ON SCREEN differ from `sha`, from a zero-context
+    diff, paired POSITIONALLY inside each hunk the way `ui/src/components/card/
+    split.ts` pairs a patch: the first `+` lines opposite `-` lines are
+    modifications, the `+` lines past them are additions, and a hunk with no
+    `+` at all is a deletion after its anchor line."""
+    if not is_tracked:
+        return [Mark(1, lines, ADDED)] if lines else []
+    found: list[Mark] = []
+    opened, start, minus, plus = False, 0, 0, 0
+    for line in _diff(tree, sha, rel, context=0, is_tracked=True).splitlines():
+        hunk = HUNK.match(line)
+        if hunk is not None:
+            if opened:
+                found.extend(_marks_of(start, minus, plus))
+            opened, start, minus, plus = True, int(hunk.group(1)), 0, 0
+        elif opened and line.startswith("-"):  # before the first `@@` the file
+            minus += 1  # headers `---`/`+++` are not lines of anybody's file
+        elif opened and line.startswith("+"):
+            plus += 1
+    if opened:
+        found.extend(_marks_of(start, minus, plus))
+    return found
+
+
+def _marks_of(start: int, minus: int, plus: int) -> list[Mark]:
+    """One hunk's marks, positionally paired."""
+    if plus == 0:
+        anchor = max(start, 1)  # `+0,0`: the deletion sits at the very top
+        return [Mark(anchor, anchor, DELETED)]
+    paired = min(minus, plus)
+    found = [Mark(start, start + paired - 1, MODIFIED)] if paired else []
+    if plus > paired:
+        found.append(Mark(start + paired, start + plus - 1, ADDED))
+    return found
+
+
+def patch_of(tree: Path, sha: str, rel: str, *, is_tracked: bool, cap: int = CAP) -> tuple[str, bool]:
+    """(text, truncated) — the same unified patch the Worktrees page draws,
+    for one file of the working copy against `sha`."""
+    return patch.capped(_diff(tree, sha, rel, context=3, is_tracked=is_tracked), cap)
+
+
+def _diff(tree: Path, sha: str, rel: str, *, context: int, is_tracked: bool) -> str:
+    """`git diff` exits 1 when the two sides differ — that is an answer, not a
+    failure, so both codes are read and anything else is an empty patch."""
+    if is_tracked:
+        raw = run.git("diff", "--no-color", f"-U{context}", sha, "--", rel, cwd=tree)
+    else:
+        raw = run.git("diff", "--no-color", f"-U{context}", "--no-index", "--", "/dev/null", rel, cwd=tree)
+    return raw.out if raw.code in (0, 1) else ""
+
+
+def _binary(probe: bytes) -> bool:
+    """A NUL says binary outright. Bytes that are not UTF-8 say so too — unless
+    the failure sits in the last three bytes, where a codepoint the probe cut in
+    half looks exactly like one."""
+    if b"\0" in probe:
+        return True
+    try:
+        probe.decode("utf-8")
+    except UnicodeDecodeError as err:
+        return err.start < len(probe) - 3
+    return False