@appchy/jarvis 0.1.36 → 0.1.39

package/harness/harness/git.py

@@ -0,0 +1,775 @@
+"""A board write is not done until it is in git.
+
+**The failure this closes.** The harness wrote a file and stopped. An item created
+on one machine sat untracked in that machine's clone until somebody noticed and
+recovered it by hand — it existed in no git history anywhere, and nothing was going
+to stop the next one. No sync design would have saved it, because it was never
+committed.
+
+So a mutation now **pulls, writes, commits and pushes**, and the commit is what
+makes it unloseable. There is no debounce and no window: the commit happens the
+moment the change does, because that window IS the bug. Only the push — the network
+half — is allowed to fail, and when it does the caller is told plainly and the work
+is still in git locally.
+
+**Off unless a repo asks.** The harness is shared, and a consumer that never asked
+for this must not suddenly start committing. `git.commit` is false by default; with
+it off, nothing in this file runs and the record stays where it was.
+
+**The trailer IS the activity record.** Every board commit carries:
+
+    Work-Item: <name>
+    Work-Event: <kind>          one line per event the command caused
+    Work-Machine: <host>
+    Work-Session: <run>         omitted when nothing names one
+
+Four things read that format, so it is a rule rather than a convention — see the
+repo's own architecture docs. Who, when and which branch are NOT trailers: git
+already knows them, and a second copy is a second thing to drift.
+
+**Coordination never enters git.** A `.claim` belongs to a machine and a moment, not
+to a branch, and a `.verify` naming the pid running this checkout's gates is the same
+kind of fact. Both are filtered out of every commit here, whatever the configured
+paths say.
+
+**What a commit contains, exactly.** Only the configured paths, committed with a
+pathspec, so a session's unrelated staged code is neither swept in nor disturbed.
+One thing does move: if a push is rejected and the retry rebases, an autostash
+restores the session's own edits as working-tree changes rather than staged ones.
+The content survives; the staging does not.
+"""
+import contextlib
+import json
+import os
+import re
+import socket
+import subprocess
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+#: `git.*` from config — bound by `config.apply`, same as everywhere else.
+GIT: dict = {"commit": False, "push": False, "remote": "origin", "paths": ["work"]}
+
+#: Trailer keys. Named here once because four other pieces of work read them, and a
+#: format that drifts breaks the record silently rather than loudly.
+ITEM, EVENT, MACHINE, SESSION = "Work-Item", "Work-Event", "Work-Machine", "Work-Session"
+
+#: Never committed, whatever `git.paths` says. A claim is coordination: it lives on
+#: the machine that granted it, for as long as it is good for, and a replicated one
+#: is two machines holding the same item with neither knowing. A verify run is the
+#: same kind of fact — a pid on one box, true for the minutes it takes — and a
+#: committed one would tell every other checkout a build is running inside it.
+CLAIM = ".claim"
+LOCAL = frozenset({CLAIM, ".verify"})
+
+_NET_TIMEOUT = 120
+_ATTEMPTS = 3
+
+#: Between an event's fields in the commit body. `_flat` keeps it out of the values
+#: themselves, which is what lets the body be read back exactly.
+SEP = " · "
+
+
+def _flat(value) -> str:
+    """One line, no separator. A field's own text may say anything; what it may not
+    do is look like the end of itself."""
+    return str(value).replace("\n", " ").replace("\r", " ").replace(SEP, " - ")
+
+
+#: Commands that read the origin before they act. Performance only: what gets
+#: COMMITTED is driven by what actually changed, so a name missing from this set
+#: costs a stale pre-pull and can never cost a write. `sync` is absent because it
+#: refreshes on its own, and being in both places is two fetches for one command.
+WRITES = frozenset({
+    "task-new", "epic-new", "feature-new", "version-new", "domain-new", "system-new",
+    "place", "move", "handoff", "plan", "session", "release", "archive",
+    "next", "drop", "ask", "answer", "verify", "observed", "id-new", "readme",
+    "migrate-owner",
+})
+
+
+def enabled() -> bool:
+    """Whether this repo has asked for its board writes to land in git."""
+    return bool(GIT.get("commit"))
+
+
+def machine() -> str:
+    """Which machine acted. `WORK_MACHINE` where something knows a better name for
+    this box than its hostname — a daemon that already has an identity for it —
+    else the hostname, which every machine has and nobody has to configure."""
+    return (os.environ.get("WORK_MACHINE") or socket.gethostname() or "").strip()
+
+
+def _git(repo, *argv, timeout=30):
+    """Run one git command. Returns (code, stdout, stderr); a git that is missing or
+    hangs is a non-zero code with a reason, never an exception — a board write must
+    not die because the transport did."""
+    try:
+        p = subprocess.run(["git", *argv], cwd=str(repo), capture_output=True,
+                           text=True, timeout=timeout)
+        return p.returncode, p.stdout, p.stderr
+    except subprocess.TimeoutExpired:
+        return 1, "", f"git {argv[0]} timed out after {timeout}s"
+    except (OSError, subprocess.SubprocessError) as e:
+        return 1, "", str(e)
+
+
+#: Git takes `index.lock` for the whole of an `add` or a `commit`, so two board
+#: writes at the same instant are one commit and one loser. Measured, four at once:
+#: one committed, three reported `could not commit the board write` — and were WRONG
+#: to, because the winner's pathspec had already swept their files in. A write that
+#: landed must never report as a write that failed.
+_LOCK = re.compile(r"index\.lock|Unable to create.*lock|another git process", re.I)
+_LOCK_TRIES = 5
+_LOCK_WAIT = 0.2
+
+#: Board writes take turns. Only the COMMIT is serialised, never the command — some
+#: commands run a test suite, and a lock held across `verify` would stall every
+#: other agent in the repo for the length of a build.
+_HOLD = "work-board.lock"
+_HOLD_WAIT = 0.1
+_HOLD_TRIES = 100
+#: A lock older than this belonged to a process that died holding it. Generous
+#: against a commit, which takes milliseconds, and still short enough that a crash
+#: at 3am does not strand the board until somebody notices.
+_HOLD_STALE = 120
+
+
+def _locking(repo, *argv, timeout=30):
+    """`_git`, but a lost race waits and asks again rather than dropping the write."""
+    for attempt in range(_LOCK_TRIES):
+        code, out, err = _git(repo, *argv, timeout=timeout)
+        if code == 0 or not _LOCK.search(err or ""):
+            return code, out, err
+        if attempt < _LOCK_TRIES - 1:
+            time.sleep(_LOCK_WAIT * (attempt + 1))
+    return code, out, err
+
+
+@contextlib.contextmanager
+def _hold(repo):
+    """Serialise the commit against other board writes on this machine.
+
+    In the git directory rather than the work tree, because it is machine-local
+    coordination and belongs where `.claim` belongs — nowhere near a branch. A lock
+    that cannot be taken is WAITED for and then ignored: the commit is the thing
+    that matters, and blocking a board write forever to protect a lock would be the
+    lock winning over the work it exists to protect.
+    """
+    code, out, _ = _git(repo, "rev-parse", "--absolute-git-dir")
+    lock = Path(out.strip()) / _HOLD if code == 0 and out.strip() else None
+    held = False
+    for _ in range(_HOLD_TRIES):
+        if lock is None:
+            break
+        try:
+            os.close(os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY))
+            held = True
+            break
+        except FileExistsError:
+            try:
+                if time.time() - lock.stat().st_mtime > _HOLD_STALE:
+                    lock.unlink()
+                    continue
+            except OSError:
+                pass
+            time.sleep(_HOLD_WAIT)
+        except OSError:
+            break
+    try:
+        yield
+    finally:
+        if held:
+            try:
+                lock.unlink()
+            except OSError:
+                pass
+
+
+def is_repo(repo) -> bool:
+    return _git(repo, "rev-parse", "--git-dir")[0] == 0
+
+
+def ignored(repo) -> list:
+    """Which configured paths git is ignoring — the silent version of this whole
+    failure, and the one that wears a success's clothes.
+
+    A repo that asks for the guarantee with `work/` in its `.gitignore` gets a
+    write on disk, a green `doctor`, and an item in no git history anywhere: the
+    exact failure this file exists to close. `git status` cannot report it, because
+    an ignored file is not untracked to git — it is invisible. So it is asked for
+    by name, where the answer is cheap: once at `doctor`, and once at the moment a
+    write finds nothing to commit.
+    """
+    paths = [p for p in (GIT.get("paths") or []) if p]
+    if not paths:
+        return []
+    code, out, _ = _git(repo, "check-ignore", "--", *paths)
+    # By LINE, not by whitespace: a configured path is free to contain a space, and
+    # splitting one into two paths that do not exist would report a failure nobody
+    # can act on.
+    return sorted({p for p in out.splitlines() if p.strip()}) if code == 0 else []
+
+
+def has_remote(repo, name: str) -> bool:
+    """Whether a remote by that name exists. `doctor` asks, so a repo pushing to a
+    name nothing answers to hears it once rather than on every board write."""
+    code, out, _ = _git(repo, "remote")
+    return code == 0 and name in out.split()
+
+
+def refresh(repo) -> str:
+    """Bring the branch up to date before acting. Returns "" when it worked, or
+    when there was nothing to do; else one line saying why not.
+
+    Fast-forward only, on purpose: this runs before ordinary commands, and a command
+    that quietly rebased somebody's branch as a side effect of listing the board
+    would be a far worse surprise than a stale read. When the branch has diverged
+    this does nothing and says so; the push path below is where a rebase is asked
+    for explicitly.
+    """
+    if not GIT.get("push"):
+        # Not a failure, and not worth saying on every write: a repo that commits
+        # without pushing has no origin to be behind in the first place. `sync` says
+        # it once, where somebody actually asked.
+        return ""
+    code, _, err = _git(repo, "fetch", GIT["remote"], timeout=_NET_TIMEOUT)
+    if code != 0:
+        return f"could not reach {GIT['remote']}: {_tail(err)}"
+    # A branch nobody tracks has nothing to fast-forward FROM. That is an ordinary
+    # state for a branch cut this morning, not a problem, so it says nothing — a
+    # warning on every write is a warning people learn to scroll past.
+    if _git(repo, "rev-parse", "--abbrev-ref", "@{upstream}")[0] != 0:
+        return ""
+    before = _git(repo, "rev-parse", "HEAD")[1].strip()
+    code, _, err = _git(repo, "merge", "--ff-only", "@{upstream}")
+    if code != 0:
+        return f"not fast-forwarded: {_tail(err)}"
+    after = _git(repo, "rev-parse", "HEAD")[1].strip()
+    if not before or before == after:
+        return ""
+    # The ground moved. WHAT moved and WHO moved it, because that is the question a
+    # session actually has at this moment — not that a fetch happened, which it can
+    # see, but whether the plan it is holding is still the plan, and who to ask.
+    from . import peers
+    return peers.arrivals(_log(repo, f"{before}..{after}"))
+
+
+#: How often the origin is asked how far ahead it is. Each `work` run is its own
+#: process, so the memo cannot live in memory — it is recorded inside `.git/`, which
+#: is never committed and belongs to exactly the clone the answer is about.
+STALENESS_TTL = 60
+_PROBE = "work-origin-probe.json"
+#: The probe runs on `list` and `status` — READS, and the most-run commands there
+#: are. `_NET_TIMEOUT` is the budget for a push, where waiting is the point; a black
+#: -holed origin held `work list` for two full minutes on it. A read that cannot get
+#: an answer quickly is better off saying it could not.
+_PROBE_TIMEOUT = 10
+
+
+def _probe_path(repo):
+    d = _git(repo, "rev-parse", "--git-dir")[1].strip()
+    return (Path(repo) / d / _PROBE) if d else None
+
+
+def _last_probe(repo) -> tuple:
+    """`(age_seconds, reachable, last_success_iso)` of the last probe.
+
+    Its OUTCOME is recorded, not merely its time. `FETCH_HEAD`'s mtime looks like the
+    obvious answer and is a trap: git touches it on a fetch that FAILED too, so a
+    clone that cannot reach its origin reads its own failed attempt back as a recent
+    successful sync — and then reports itself current, which is precisely the lie this
+    is here to end.
+
+    The third field is the last time the origin was actually REACHED, which is a
+    different fact from when it was last asked. Conflating them puts a fresh
+    timestamp next to the words "last synced" on a clone that has not synced at all —
+    the same lie, one layer further down, in the sentence instead of the cache.
+    """
+    p = _probe_path(repo)
+    try:
+        data = json.loads(p.read_text())
+        return (time.time() - float(data["at"]), bool(data["reachable"]),
+                str(data.get("synced", "")))
+    except (OSError, ValueError, KeyError, TypeError, AttributeError):
+        return None, None, ""
+
+
+def _record_probe(repo, reachable: bool) -> str:
+    """Remember this attempt, and carry the last SUCCESS forward across failures.
+
+    A failed probe advances the attempt clock and nothing else: the only honest
+    answer to "when did this board last see its origin" is unchanged by an attempt
+    that did not.
+    """
+    now = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+    synced = now if reachable else (_last_probe(repo)[2] or "")
+    p = _probe_path(repo)
+    try:
+        p.write_text(json.dumps({"at": time.time(), "reachable": reachable,
+                                 "synced": synced}))
+    except (OSError, AttributeError):
+        pass
+    return synced
+
+
+def behind(repo) -> dict:
+    """Where this checkout stands against its upstream.
+
+    `{}` when the branch tracks nothing — a branch cut this morning has no origin to
+    be behind, and a notice every new branch earns for nothing is one people learn to
+    scroll past. Otherwise `ref` and EITHER `behind` (a fact, and only ever when the
+    origin actually answered) or `reachable: False` with when it was last really seen.
+
+    Counting against a remote-tracking ref nobody refreshed is the failure this
+    closes: it answers zero with total confidence, which is how a board nine days
+    stale reported itself current.
+    """
+    ref = _git(repo, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}")[1].strip()
+    if not ref:
+        return {}
+    age, was_reachable, when = _last_probe(repo)
+    # Inside the window the last answer still stands — including a negative one, which
+    # is why the outcome is stored rather than just the timestamp.
+    if age is None or age > STALENESS_TTL:
+        was_reachable = _git(repo, "fetch", "--quiet", "--no-tags",
+                             GIT.get("remote") or "origin",
+                             timeout=_PROBE_TIMEOUT)[0] == 0
+        when = _record_probe(repo, was_reachable)
+    if not was_reachable:
+        return {"ref": ref, "reachable": False, "synced": when}
+    count = _git(repo, "rev-list", "--count", f"HEAD..{ref}")[1].strip()
+    if not count.isdigit():
+        return {"ref": ref, "reachable": False, "synced": when}
+    return {"ref": ref, "reachable": True, "behind": int(count), "synced": when}
+
+
+def staleness(repo) -> str:
+    """One line for a reader, or "" when this checkout is level with its origin.
+
+    Silent on the happy path by design — the notice has to mean something the moment
+    it appears, and a board that says "current" on every command teaches nobody to
+    read it.
+    """
+    # `push` as well as `commit`: a repo that commits without ever sending has no
+    # origin to be behind, `refresh` already stays silent about it for that reason,
+    # and `sync` refuses to pull in that mode — so the notice would spend a network
+    # round trip to recommend a command that declines to help.
+    if not enabled() or not GIT.get("push"):
+        return ""
+    state = behind(repo)
+    if not state:
+        return ""
+    from .tree import cli
+
+    if not state.get("reachable"):
+        seen = state.get("synced")
+        return (f"cannot reach {state['ref']} — this board may not be current"
+                + (f", last synced {seen}" if seen
+                   else " and has never reached its origin"))
+    n = state.get("behind") or 0
+    if n <= 0:
+        return ""
+    return (f"this board is {n} commit(s) behind {state['ref']} — you are reading an "
+            f"older world than the origin's. `{cli()} sync` catches up")
+
+
+def changed(repo) -> tuple:
+    """What a commit would carry: `(paths, untracked)`, claims excluded.
+
+    Both are needed because they are staged differently. An untracked file has to be
+    ADDED or the commit cannot name it — that is the lost item's own shape, a new
+    task folder git had never heard of. Everything else, including a file somebody
+    deleted, is taken from the working tree by the commit itself; running `git add`
+    over a path already staged for deletion fails outright, since it is in neither
+    the worktree nor the index for the pathspec to match.
+    """
+    args = ["status", "--porcelain", "-z", "--untracked-files=all", "--no-renames",
+            "--"] + list(GIT.get("paths") or [])
+    code, out, _ = _git(repo, *args)
+    if code != 0:
+        return [], []
+    paths, untracked = [], []
+    for entry in out.split("\0"):
+        # `XY <path>` — two status columns, a space, then the path, unquoted
+        # because of `-z`.
+        if len(entry) > 3:
+            state, p = entry[:2], entry[3:]
+            if Path(p).name in LOCAL:
+                continue
+            paths.append(p)
+            if state == "??":
+                untracked.append(p)
+    return paths, untracked
+
+
+def only_board_moved(repo, sha: str) -> bool:
+    """Is everything between `sha` and HEAD a board file?
+
+    The completion gate refuses when the code moved since verify passed, which is
+    right — and once board writes commit, `verify` recording its own result MOVES
+    HEAD, so the gate started refusing on evidence it had just produced. A commit
+    carrying nothing but `git.paths` cannot change what a test run proved, so it
+    does not count as the code moving.
+    """
+    if not enabled() or not sha:
+        return False
+    code, out, _ = _git(repo, "diff", "--name-only", f"{sha}..HEAD")
+    if code != 0:
+        return False
+    roots = [r.rstrip("/") for r in (GIT.get("paths") or [])]
+    return all(any(f == r or f.startswith(f"{r}/") for r in roots)
+               for f in out.splitlines() if f.strip())
+
+
+def land(repo, item: str, rows: list) -> tuple:
+    """Commit what changed and push it. Returns (committed, pushed, note).
+
+    `note` is what to tell the caller — empty when everything landed. A push that
+    cannot land is NOT a failure of the write: the change is committed, which is
+    what makes it unloseable, and the note says how to send it.
+    """
+    # Asked FIRST, and not after `changed`: a directory that is not a repo makes
+    # `git status` fail, `changed` return nothing, and the write look like a no-op
+    # with nothing to say. Silence is the one answer this must never give — a repo
+    # that asked for the guarantee and cannot have it needs telling.
+    if not is_repo(repo):
+        return False, False, "not a git repository — the board write is on disk only"
+
+    # Only the commit takes the hold; the push is left outside it, because a slow
+    # network must not be able to stall every other board write on this machine.
+    with _hold(repo):
+        paths, untracked = changed(repo)
+        if not paths:
+            # Nothing to commit is usually the ordinary answer — a read, or a write
+            # that changed nothing — and says nothing. Two cases are not ordinary.
+            skipped = ignored(repo)
+            if skipped:
+                # "Nothing changed" is a lie git cannot help telling about a file it
+                # was told to ignore, and this is where a repo finds out before the
+                # item it just made goes missing.
+                return False, False, (
+                    f"git is ignoring {', '.join(skipped)}, so NOTHING here reaches "
+                    f"git — a board write cannot be committed while it is gitignored. "
+                    f"Un-ignore it, or point git.paths at a tree that is tracked.")
+            if rows:
+                # This command DID write, and its changes are gone from the working
+                # tree: a board write that landed a moment earlier committed the
+                # whole of `git.paths` and carried them along. The work is in git.
+                # What it is not is filed under its own name — see the note below.
+                return False, False, (
+                    "carried by a board write that committed a moment earlier — the "
+                    "change is in git, under that commit's item rather than this one")
+            return False, False, ""
+
+        if untracked:
+            code, _, err = _locking(repo, "add", "--", *untracked)
+            if code != 0:
+                return False, False, f"could not stage the board write: {_tail(err)}"
+
+        subject, body, trailers = _message(item, rows)
+        # A command that recorded no event has no body to write, and repeating the
+        # subject there would only be a second copy of it.
+        message = ["-m", subject] + (["-m", body] if body else []) + ["-m", trailers]
+        code, _, err = _locking(repo, "commit", "--no-verify", *message, "--", *paths)
+        if code != 0:
+            return False, False, f"could not commit the board write: {_tail(err)}"
+
+    if not GIT.get("push"):
+        return True, False, ""
+    pushed, why = _push(repo)
+    return True, pushed, why
+
+
+def _push(repo) -> tuple:
+    """Push, and when the branch moved under us, rebase onto the new tip and try
+    again. Returns (pushed, why-not).
+
+    A rebase that hits a conflict is aborted rather than left half-done: a session
+    dropped into a conflicted rebase it did not ask for cannot get on with its work,
+    and the commit is already safe.
+    """
+    remote = GIT["remote"]
+    why = ""
+    for attempt in range(_ATTEMPTS):
+        # `-u` on purpose, and it is a fix rather than a nicety: without it a branch
+        # never gets an upstream, `@{upstream}` never resolves, and `sync` — the
+        # documented recovery for a push that could not land — read that as "nothing
+        # waiting" and left the commit sitting local forever. Every branch an agent
+        # cuts starts in exactly that state.
+        code, _, err = _git(repo, "push", "-u", remote, "HEAD", timeout=_NET_TIMEOUT)
+        if code == 0:
+            return True, ""
+        why = _tail(err)
+        if not re.search(r"rejected|non-fast-forward|fetch first|behind", err, re.I):
+            break
+        if attempt == _ATTEMPTS - 1:
+            break
+        _, pre, _ = _git(repo, "rev-parse", "HEAD")
+        code, _, rebase_err = _git(repo, "-c", "rebase.autoStash=true", "pull",
+                                   "--rebase", remote, timeout=_NET_TIMEOUT)
+        if code != 0:
+            _git(repo, "rebase", "--abort")
+            why = f"the branch moved and the rebase onto it did not apply: {_tail(rebase_err)}"
+            break
+        stranded = _unstash(repo, pre.strip())
+        if stranded:
+            why = stranded
+            break
+    from .tree import cli
+
+    return False, (f"committed here, NOT pushed — {why}. The work is in git locally; "
+                   f"`{cli()} sync` sends it when you can reach {remote}.")
+
+
+def _unstash(repo, pre: str) -> str:
+    """Undo a pull whose autostash could not be put back. Returns why-not, or "".
+
+    `pull --rebase` exits **0** when the rebase itself lands and only the autostash
+    pop conflicts, so without this the caller reads success: the push goes out and
+    the session is told the write was pushed, while its working tree is left holding
+    conflict markers it did not ask for and its own uncommitted edits sit in a stash
+    nobody mentioned. Going back to where the pull started puts those edits back
+    where their author left them, which is the same promise the abort above makes.
+
+    The board commit is never at risk — it was made before any of this, and it is
+    inside `pre`. It stays committed and unpushed, which is what `sync` is for.
+    """
+    _, unmerged, _ = _git(repo, "diff", "--name-only", "--diff-filter=U")
+    if not unmerged.strip() or not pre:
+        return ""
+    clash = "the branch moved, and your uncommitted edits clash with what was on it"
+    # Every step is checked before the next one claims it happened. Saying "your
+    # working tree is as you left it" over a reset that did not run would be the
+    # same false report this whole function exists to stop.
+    code, _, err = _locking(repo, "reset", "--hard", pre)
+    if code != 0:
+        return (f"{clash}, and the tree could not be put back ({_tail(err)}) — "
+                f"your edits are in `git stash`, and the rebase is half-applied")
+    code, _, err = _locking(repo, "stash", "pop")
+    if code != 0:
+        return f"{clash} — nothing was rebased, and your edits are in `git stash` ({_tail(err)})"
+    return f"{clash} — nothing was rebased and your working tree is as you left it"
+
+
+def _message(item: str, rows: list) -> tuple:
+    """(subject, body, trailers) for one board commit.
+
+    The body is one line per event, in the order they happened, carrying that
+    event's own detail as prose. The TRAILERS stay four keys wide — that is the part
+    other work reads, and every field added to it is a field that can drift.
+    """
+    kinds = [str(r.get("event", "")) for r in rows if r.get("event")]
+    # No event is a legal commit: some commands write the tree without recording
+    # one. It carries `Work-Item` and no `Work-Event`, so it is greppable by item
+    # and simply absent from the activity log — which is what it was already. With
+    # no item either, it is a hand edit somebody made to the tree, swept up by
+    # whatever ran next.
+    subject = (f"docs(work): {kinds[-1] if kinds else 'changed'} {item}".strip()
+               if item else "docs(work): board edits")
+
+    lines = []
+    for r in rows:
+        detail = SEP.join(f"{k}={_flat(v)}" for k, v in sorted(r.items())
+                          if k not in ("ts", "event", "name", "by"))
+        lines.append(f"{r.get('event', '')}  {detail}".rstrip())
+
+    trailers = [f"{ITEM}: {item}"] if item else []
+    trailers += [f"{EVENT}: {k}" for k in kinds]
+    if machine():
+        trailers.append(f"{MACHINE}: {machine()}")
+    who = _session()
+    if who:
+        trailers.append(f"{SESSION}: {who}")
+    return subject, "\n".join(lines), "\n".join(trailers)
+
+
+def _session() -> str:
+    return (os.environ.get("WORK_INSTANCE")
+            or os.environ.get("CLAUDE_CODE_SESSION_ID", "")).strip()
+
+
+#: One commit, rendered for parsing: NUL between records, unit separators inside.
+_FORMAT = "%x00%H%x1f%aI%x1f%an%x1f%B"
+
+
+def _log(repo, *extra) -> list:
+    """Board events out of `git log`, oldest first. One parser for every caller, so
+    what `digest` reads and what a pull reports can never be two different shapes."""
+    code, out, _ = _git(repo, "log", "--reverse", f"--format={_FORMAT}", "-E",
+                        f"--grep=^{ITEM}: ", *extra, timeout=60)
+    if code != 0:
+        return []
+    rows = []
+    for record in out.split("\0"):
+        if record.strip():
+            rows.extend(_events(record))
+    return rows
+
+
+def read(repo, since: str = "", name: str = "") -> list:
+    """The board's history, oldest first, read back out of the commits.
+
+    Local: `git log` reads this clone and nothing else, so history costs no network
+    and has no rate limit. There is no index and no cache — a fact that can be
+    derived is not stored, and this one can.
+    """
+    rows = _log(repo, *([f"--since={_since(since)}"] if since else []))
+    return [r for r in rows if not name or r.get("name") == name]
+
+
+def _events(record: str) -> list:
+    """Every event one commit carried, back in the shape the readers expect."""
+    parts = record.split("\x1f")
+    if len(parts) < 4:
+        return []
+    sha, when, author, message = parts[0], parts[1], parts[2], parts[3]
+    trailers = _trailers(message)
+    item = (trailers.get(ITEM) or [""])[0]
+    kinds = trailers.get(EVENT) or []
+    if not item or not kinds:
+        return []
+    details = _details(message, kinds)
+    who = (trailers.get(SESSION) or [""])[0]
+    host = (trailers.get(MACHINE) or [""])[0]
+    out = []
+    for kind in kinds:
+        e = {"ts": _utc(when), "event": kind, "name": item, "sha": sha[:12],
+             "author": author}
+        if who:
+            e["by"] = who
+        if host:
+            e["machine"] = host
+        e.update(details.get(kind) or {})
+        out.append(e)
+    return out
+
+
+#: A plain calendar day, which is the only `--since` the skill documents.
+_DAY = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def _since(since: str) -> str:
+    """`--since` on the same clock as the rows it selects.
+
+    Git fills the fields a date leaves out from NOW, not from midnight — so
+    `--since 2026-08-20` means *the 20th at the current time of day*, and `work
+    digest --since <today>` answered with the last few seconds of the shift and
+    nothing else. Measured: two commits on the 19th, `--since=2026-08-19` returned
+    neither; a commit made this morning, `--since=<today>` returned none.
+
+    The file backend compares the UTC timestamp against the date as text, so the day
+    starts at UTC midnight there. Anchoring the day makes both backends answer the
+    same question. Anything that is not a plain day — git's own fuzzy forms, "2
+    weeks ago" — is git's to interpret and passes through untouched.
+    """
+    return f"{since}T00:00:00+00:00" if _DAY.match(since or "") else since
+
+
+def _utc(when: str) -> str:
+    """One clock, one format, whichever backend answered.
+
+    `%aI` is the author's own wall time and carries their offset, so the instant is
+    recoverable — but truncated to its first 19 characters it becomes a bare local
+    time that READS as UTC, which is what the file backend actually records. Two
+    records of the same board, hours apart, with nothing on either to say which.
+    Converted here rather than trimmed, into the shape `events` already writes.
+    """
+    try:
+        return (datetime.fromisoformat(when).astimezone(timezone.utc)
+                .replace(microsecond=0).isoformat())
+    except ValueError:
+        # A git answering in some other dialect is not worth dying over — the date is
+        # the least of what this row carries. Returned WHOLE rather than trimmed to
+        # 19 characters: a trim is what produced a local time wearing UTC's clothes
+        # in the first place, and a fallback that restores the original bug quietly
+        # is worse than one that reads oddly and can be seen.
+        return when
+
+
+_TRAILER = re.compile(r"^(Work-[A-Za-z]+):[ \t]*(.*)$")
+
+
+def _trailers(message: str) -> dict:
+    out = {}
+    for line in message.splitlines():
+        m = _TRAILER.match(line.strip())
+        if m:
+            out.setdefault(m.group(1), []).append(m.group(2).strip())
+    return out
+
+
+def _details(message: str, kinds) -> dict:
+    """The body's per-event payload, matched back to its event by name.
+
+    A round trip rather than prose, so `log`, `digest` and `status` print the same
+    thing whichever backend the repo runs. `_flat` is what makes it safe: the
+    separator can never appear inside a value, so a question with an odd character
+    in it comes back whole instead of splitting into a field nobody wrote.
+    """
+    out = {}
+    for line in message.splitlines():
+        line = line.strip()
+        if _TRAILER.match(line):
+            continue
+        head, _, rest = line.partition("  ")
+        if head not in kinds or not rest.strip() or head in out:
+            continue
+        fields = {}
+        for chunk in rest.split(SEP):
+            key, sign, value = chunk.partition("=")
+            if sign and key.strip():
+                fields[key.strip()] = value.strip()
+        out[head] = fields
+    return out
+
+
+def cmd_sync(args=None) -> int:
+    """Pull the board fresh, and send anything committed here that never got out.
+
+    The read half is what an agent runs when it is not sure something moved under
+    it — it changes nothing, so it is safe to run before acting on anything. The
+    write half is the recovery path for a push that could not land at the time.
+    """
+    from .tree import die, locate_work_root
+    if not enabled():
+        die("this repo does not write its board to git — set `git.commit` in "
+            ".claude/work.config.json if you want it to")
+    root = locate_work_root()[0]
+    if root is None:
+        die("no work/ tree found — nothing here to sync")
+    repo = root.parent
+    if not is_repo(repo):
+        die(f"{repo} is not a git repository")
+
+    if not GIT.get("push"):
+        print("pulled     git.push is off — there is no origin to refresh from")
+        print("pushed     git.push is off — this repo commits but never sends")
+        return 0
+    note = refresh(repo)
+    print(f"pulled     {'up to date' if not note else note}")
+    # A branch with no upstream cannot answer "how far ahead am I" — and the answer
+    # this asks for is the one that decides whether to send. Unknown therefore means
+    # SEND: a `sync` that stays silent about work it never pushed is the failure it
+    # was written to recover from.
+    code, out, _ = _git(repo, "rev-list", "--count", "@{upstream}..HEAD")
+    ahead = out.strip() if code == 0 else ""
+    if ahead == "0":
+        print("pushed     nothing waiting")
+        return 0
+    pushed, why = _push(repo)
+    waiting = f"{ahead} commit(s)" if ahead else "this branch"
+    print(f"pushed     {waiting} to {GIT['remote']}" if pushed else f"pushed     {why}")
+    return 0 if pushed else 1
+
+
+def _tail(text: str) -> str:
+    """Git's first real complaint. The FIRST line, not the last: git follows a
+    `fatal:` with a paragraph of advice, and the closing line of that paragraph
+    ("…and the repository exists.") reads as gibberish on its own."""
+    for line in (text or "").splitlines():
+        line = line.strip()
+        if line and not line.startswith("hint:"):
+            return line[:200]
+    return "no reason given"