taskops-cli 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

taskops/_version.py

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

taskops/cli/gitremote.py

@@ -0,0 +1,198 @@
+"""`taskops remote git` — this checkout's git, pointed at the board's own repo.
+
+    taskops remote git                  print the address and the two lines to paste
+    taskops remote git --add            wire them here (remote `taskops`, no origin touched)
+    taskops remote git <host>/<board>   another board's address, explicitly
+
+§16, "The host becomes the remote", left one thing on the DEV's side unsaid: the
+host serves `https://<host>/<board>/repo.git` and nothing in the CLI spelled that
+address out loud, so the only way to reach it was to read `http/gitpack.py`. This
+command is that sentence, and it is the same act as `taskops remote add` —
+recording an address — so it stays on that verb rather than becoming a twelfth
+command.
+
+**`origin` is never written, and `--name origin` is REFUSED** — not "left alone
+if it exists": refused outright. A checkout's `origin` is somebody's working
+setup, very often their GitHub, and no state of it is this command's to decide,
+its absence included. So the remote is `taskops`, `--name <other>` when even
+that is taken, and a name in use is a refusal naming that flag instead of a
+`set-url`. Adding a remote is CONNECTING; repointing an `origin` is managing.
+
+**The credential is a HELPER, never a URL.** The obvious spelling —
+`https://x:<token>@host/<board>/repo.git` — is refused here, and not on taste:
+`git remote add` writes its URL into `.git/config`, plaintext with the repo's
+own permissions, so that spelling persists a live session token in the one file
+nobody thinks to look at. It is also WRONG within the hour, because a taskops
+session expires (`session.py`) and a token baked into a config cannot renew
+itself. So what gets configured is `credential.<host>.helper`, and the helper is
+this CLI: git asks for the password at push time, `credential()` below mints or
+renews a session from the ssh key already on disk (`identity.establish`, the
+same one every board verb uses), hands git the token on a pipe, and NOTHING is
+written. One credential story, §19's, through git's own door.
+
+**Where the address is SPELLED, and where it is not.** This command prints the
+exact URL for one board; `board ls` prints the shape (`shape`, below). The board
+PAYLOAD gains no `repo_url`: the server cannot know its own public address (a
+proxy, a port-forward, the local `taskops ui` window — every reader reached it
+at an address the server never saw), so a stored one rots first and sends a dev
+to the wrong host. The address is (the host you asked) + `/<board>/repo.git`, a
+derivation the CLIENT can always do right and the server never can.
+"""
+
+from __future__ import annotations
+
+import sys
+import argparse
+from pathlib import Path
+
+from . import commands
+from .. import identity
+from ..board import find_root, read_config
+from .remote import named, recorded_host
+from .._errors import TaskopsError
+from ..gitwork import run
+
+REMOTE = "taskops"
+"""The name added by `--add` — never `origin`, and never a fork's `upstream`:
+the two names git culture has already spent."""
+
+USERNAME = "x"
+"""Basic wants a username and the token is the whole credential, so the field is
+decoration — the same `x` `http/gitpack.py` documents on its side."""
+
+SUFFIX = "repo.git"  # `http/routes.py`'s own first segment, spelled once here
+
+NOT_ORIGIN = (
+    "`origin` is git's and this command does not take it over — that remote is "
+    "somebody's own setup (very often their GitHub), and repointing it is not "
+    "connecting, it is rewriting. The default name works: taskops remote git --add"
+)
+
+TAKEN = (
+    "this checkout already has a remote called {name}, pointing at {url} — "
+    "`taskops remote git --add --name <other>` adds one under a name that is free. "
+    "Nothing here rewrites a remote you configured."
+)
+
+HELPER_TAKEN = (
+    "a credential helper for {host} is already configured here ({have}) — leave it, "
+    "or replace it yourself with `git config --local credential.{host}.helper …`. "
+    "This command does not overwrite a credential you set up."
+)
+
+
+def url_for(host: str, board: str) -> str:
+    """`https://<host>/<board>/repo.git` — spelled ONCE on the client side."""
+    return f"{host.rstrip('/')}/{board}/{SUFFIX}"
+
+
+def shape(host: str) -> str:
+    """What `board ls` says about where the git lives — the SHAPE, on the line it
+    already prints, once. Not per row: the address is the same derivation for
+    every board on the host, and repeating it N times is noise, not discovery."""
+    return f"   ·   git: {host.rstrip('/')}/<board>/{SUFFIX} (taskops remote git)"
+
+
+def helper_command(python: str) -> str:
+    """What git runs to get the password. `!` is git's own marker for "this is a
+    shell command, not a `git-credential-<name>` on PATH", and the interpreter is
+    named absolutely for `gitwork/install.py`'s reason: the hooks git fires do not
+    inherit whatever virtualenv was active when this was configured."""
+    return f'!"{python}" -m taskops.cli hook credential'
+
+
+def wire(args: argparse.Namespace, python: str) -> int:
+    """`taskops remote git [--add] [--name <n>]` — print it, or write it."""
+    root = find_root(Path.cwd())
+    host, board = named(str(args.url))
+    url, name = url_for(host, board), str(getattr(args, "name", "") or REMOTE)
+    helper = helper_command(python)
+    if name == "origin":
+        raise TaskopsError(NOT_ORIGIN)
+    if not bool(getattr(args, "add", False)):
+        print(url)
+        print(f"  git remote add {name} {url}")
+        print(f"  git config --local credential.{host}.helper '{helper}'")
+        print(f"  git push {name} <branch>   — your ssh key mints the token, nothing to type")
+        print("  or write both here:  taskops remote git --add")
+        return 0
+    _remote(root, name, url)
+    _helper(root, host, helper)
+    print(f"{name}  {url}")
+    print(f"  credential.{host}.helper mints a session from your ssh key at push time")
+    print(f"  no token is written anywhere — git push {name} <branch>")
+    return 0
+
+
+def _remote(root: Path, name: str, url: str) -> None:
+    """Add it, or refuse. `git remote add` would refuse a duplicate itself, and
+    the refusal is intercepted here so it names the flag that gets past it."""
+    have = run.git("remote", "get-url", name, cwd=root)
+    if have.ok and have.out.strip():
+        if have.out.strip() == url:
+            return  # already exactly this: re-running is free and says so
+        raise TaskopsError(TAKEN.format(name=name, url=have.out.strip()))
+    run.must("remote", "add", name, url, cwd=root, why=f"cannot add the remote {name}")
+
+
+def _helper(root: Path, host: str, helper: str) -> None:
+    """Configure the helper for THIS host only: `credential.<url>` answers for
+    that URL and nothing else, which is exactly the scope of the token it hands
+    out (`session.py` mints per host)."""
+    have = run.git("config", "--local", "--get", f"credential.{host}.helper", cwd=root)
+    if have.ok and have.out.strip():
+        if have.out.strip() == helper:
+            return
+        raise TaskopsError(HELPER_TAKEN.format(host=host, have=have.out.strip()))
+    run.must(
+        "config", "--local", f"credential.{host}.helper", helper,
+        cwd=root, why=f"cannot configure the credential helper for {host}",
+    )
+
+
+def credential(text: str, rest: list[str]) -> int:
+    """git's credential helper, answering `get` and only `get`.
+
+    Protocol (`gitcredentials(7)`): the operation arrives as argv, the request as
+    `key=value` lines on stdin, the answer as `key=value` lines on stdout. An
+    unanswered request is not an error — git moves to the next helper — so every
+    reason to decline is silence, plus a line on stderr when it is a FAILURE:
+    `hooks.py`'s policy, for its reason. `store` and `erase` are declined too: a
+    helper that caches is a helper that persists a token, and minting is free.
+
+    It also declines a host that is not the one this checkout operates — the
+    second wall, and the one that matters: a checkout whose recorded host changed
+    must not sign a challenge to the old one.
+    """
+    if (rest[0] if rest else "get") != "get":
+        return 0  # store / erase: nothing is cached, so there is nothing to do
+    asked = _fields(text)
+    wanted = f"{asked.get('protocol', '')}://{asked.get('host', '')}"
+    known = recorded_host()
+    if not known or wanted != known.rstrip("/"):
+        return 0
+    root = find_root(Path.cwd())
+    config = read_config(root)
+    try:
+        token, door = identity.establish(root, known, config, "", "", commands.principal())
+    except TaskopsError as err:
+        print(f"taskops: {err}", file=sys.stderr)
+        return 0
+    if door and identity.is_own_host(config, known):
+        identity.cache_login(root, door)
+    print(f"username={USERNAME}")
+    print(f"password={token}")
+    return 0
+
+
+def _fields(text: str) -> dict[str, str]:
+    """git's request, as a dict. A blank line ends it; anything unparseable is
+    dropped rather than guessed at."""
+    out: dict[str, str] = {}
+    for line in text.splitlines():
+        if not line.strip():
+            break
+        key, sep, value = line.partition("=")
+        if sep:
+            out[key.strip()] = value.strip()
+    return out

taskops/cli/main.py

@@ -3,6 +3,8 @@
     taskops init            a local board in this repo
     taskops join <url>      join one (bare, ?token= or --invite), install the hooks
     taskops remote add <url>  the host this checkout operates, like git's origin
+    taskops remote git      the board's OWN git repository, and how to push to it:
+                            printed to paste, or --add to wire it here (never origin)
     taskops serve           host boards — an events API, no dashboard
     taskops server init     bootstrap THIS host: its owner and their ssh key
     taskops board create    make a board on a host  ·  board ls, from anywhere
@@ -20,7 +22,8 @@
     taskops invite <who>    a single-use link  ·  taskops revoke --key|--invite
     taskops tidy            remove worktrees whose work is already in the trunk
     taskops ui              the dashboard — serves it if nothing is, opens the browser
-    taskops hook …          what the two git hooks and the Claude hook call
+    taskops hook …          what the git hooks, the Claude hook and git's credential
+                            helper call — never a human
 
 Moving a card from the terminal does not exist: that is MCP. v1 grew 35
 management commands, each one a second way to do something the tools already
@@ -47,6 +50,7 @@ from . import (
     operate,
     serving,
     commands,
+    gitremote,
 )
 from ..board import find_root
 from .._errors import TaskopsError
@@ -108,6 +112,11 @@ def _run(args: argparse.Namespace) -> int:
         return 0
     if args.command == "ui":
         return serving.ui(here)
+    if str(args.which) == "credential":
+        # git's credential helper protocol: the operation is argv, the request is
+        # stdin. Read here, so `gitremote.credential` stays a pure function of
+        # what git said and the tests can hand it a request directly.
+        return gitremote.credential(sys.stdin.read(), [str(x) for x in args.rest])
     if str(args.which) == "claude":
         # Routed here and not through `commands` so the delivery hook owns its
         # own error policy end to end: it prints NOTHING, ever, including the

taskops/cli/operate.py

@@ -35,7 +35,7 @@ import argparse
 from typing import Any
 from pathlib import Path
 
-from . import team, commands
+from . import team, commands, gitremote
 from .. import _wire, _clock, identity
 from .._json import as_object
 from ..board import find_root, read_config
@@ -63,7 +63,7 @@ def board(args: argparse.Namespace) -> int:
     host, _ = address(target)
     answer = call(host, "board.list", {}, signed_in(host, args))
     rows: list[dict[str, Any]] = [as_object(row) for row in answer.get("boards", [])]
-    print(f"{host} — {len(rows)} board(s), as {answer.get('role', '?')}")
+    print(f"{host} — {len(rows)} board(s), as {answer.get('role', '?')}{gitremote.shape(host)}")
     for row in rows:
         print(f"  {row['name']:<24} {row['cards']:>4} cards  seq {row['seq']:<6} {_ago(row)}")
     return 0

taskops/cli/parser.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 
 import argparse
 
+from . import gitremote
 from ..core import forge
 
 AS_HELP = "the principal that key belongs to (default: $USER)"
@@ -28,11 +29,23 @@ def build(description: str) -> argparse.ArgumentParser:
     sub.add_parser("init", help="a local board in this repo")
     _join(sub)
     origin = sub.add_parser("remote", help="the host this checkout operates (git's origin)")
-    origin.add_argument("action", nargs="?", default="", choices=["", "add"])
-    origin.add_argument("url", nargs="?", default="", help="https://<host>")
+    origin.add_argument("action", nargs="?", default="", choices=["", "add", "git"])
+    # `add` takes the HOST; `git` takes an optional <host>/<board> and otherwise
+    # uses the recorded pair — one slot, because both are an address.
+    origin.add_argument("url", nargs="?", default="", help="add: https://<host> · git: <host>/<board>")
     origin.add_argument(
         "--replace", action="store_true", help="this checkout already names another host"
     )
+    origin.add_argument(
+        "--add",
+        action="store_true",
+        help="remote git: write the remote and the credential helper here instead of printing them",
+    )
+    origin.add_argument(
+        "--name",
+        default="",
+        help=f"remote git --add: the remote's name (default: {gitremote.REMOTE}; never origin)",
+    )
     server = sub.add_parser("serve", help="host boards")
     server.add_argument("--root", default="~/taskops-boards")
     server.add_argument("--host", default="127.0.0.1")
@@ -48,7 +61,9 @@ def build(description: str) -> argparse.ArgumentParser:
     tidy.add_argument("--trunk", default="")
     sub.add_parser("ui", help="the dashboard: serve if needed, open the browser, token included")
     hook = sub.add_parser("hook", help="internal: what the installed hooks call")
-    hook.add_argument("which", choices=["trailer", "commit", "claude"])
+    # `credential` is git's credential helper (`cli/gitremote.py`) — internal in
+    # exactly the same sense as the other three: git invokes it, never a human.
+    hook.add_argument("which", choices=["trailer", "commit", "claude", "credential"])
     hook.add_argument("rest", nargs="*")
     return parser
 

taskops/cli/remote.py

@@ -2,6 +2,7 @@
 
     taskops remote add https://taskops.example.com     record it, like git's origin
     taskops remote                                     print what is recorded
+    taskops remote git [--add]                         the board's own git repository
 
 Git asks for neither a URL nor an identity file on every push, and the two
 reasons it does not are both copied here: the address is recorded per CLONE
@@ -27,6 +28,7 @@ already chosen.
 
 from __future__ import annotations
 
+import sys
 import argparse
 from pathlib import Path
 
@@ -57,8 +59,16 @@ ALREADY = (
 
 
 def remote(args: argparse.Namespace) -> int:
-    """`add` records the host; no argument prints it, `git remote -v` style."""
+    """`add` records the host; no argument prints it, `git remote -v` style.
+
+    `git` is the third action and it belongs here rather than on a command of its
+    own: recording where the board's git lives is the same act as recording where
+    the board lives (`cli/gitremote.py` argues the whole of it)."""
+    from . import gitremote
+
     root = find_root(Path.cwd())
+    if str(args.action) == "git":
+        return gitremote.wire(args, sys.executable)
     url, known = str(args.url), recorded_host()
     if str(args.action) != "add":
         print(f"origin  {known}" if known else NO_REMOTE)

taskops/core/forge.py

@@ -54,6 +54,16 @@ def is_repo(repo: str) -> bool:
     return len(parts) == 2 and all(parts) and not any(ch.isspace() for ch in repo)
 
 
+def label(fact: dict[str, Any]) -> str:
+    """`host/owner/name` — the ONE spelling of a declared forge for a reader.
+
+    It is a key as well as a caption: `store/mirroring.py` rows the outbound
+    mirror's last word under it, so a board pointed at a new repo starts with
+    nothing said about it rather than inheriting the old one's report.
+    """
+    return f"{fact['host']}/{fact['repo']}"
+
+
 def declare(host: str, repo: str, need: str) -> dict[str, Any]:
     """A human's three words → the stored fact. Each refusal names the way out."""
     if host not in FORGES:

taskops/gitwork/bare.py

@@ -0,0 +1,122 @@
+"""The board's OWN bare repository — `<root>/<board>/repo.git` (§16, "The host
+becomes the remote"). This is what the smart-HTTP door serves and what the
+JSON diff door reads once it exists: truth the forge does not necessarily
+hold, deletable by nobody.
+
+**Created on demand by the first WRITE-credentialed request, never by a
+read.** `mounts.stores` carries the post-mortem this rule copies: a GET for a
+name nobody had heard of used to leave a board directory on disk — a write
+caused by a stranger's question. `repo.git` is truth, not cache, so the same
+rule holds one level down: an anonymous clone of a board nobody has pushed to
+answers 404 with the fact named, and the directory appears only when an
+enrolled principal's push (or its ref advertisement, which git sends first)
+asks for it. `http/gitpack.py` is the one caller and passes which case it is.
+
+**It also owns the RETIREMENT of the pull mirror** (`adopt`, below): a board
+whose only git is a `mirror.git` from §16's first amendment is migrated here,
+once, and the mirror directory removed. That lives in this module rather than in
+`mirror.py` because `mirror.py` is deleted — the thing owed to a retired
+mechanism is the history it holds, and the module that keeps histories is this
+one.
+
+**Never pruned, enforced in the repo's own config.** `receive.denyDeletes`
+and `receive.denyNonFastForwards` are written at creation, so the wall is
+git's own, checked inside the very `git receive-pack` process that would
+otherwise move the ref — there is no window between an application-level
+check and the update, no pre-receive hook to install (a hook is a script on
+disk that a later `git init` or a copy silently drops; config survives both),
+and a client's `--force` changes nothing because the refusal is the server
+process's. There is no flag that lifts either, for `board rm`'s reason (§11):
+what a force would erase here is the diff of a landed card — the board's own
+record. History rewriting, when it is ever needed, is the owner's deliberate
+act against the host's filesystem, not a verb.
+"""
+
+from __future__ import annotations
+
+from shutil import rmtree
+from pathlib import Path
+
+from . import run
+
+REPO = "repo.git"
+
+CLONE_TIMEOUT = 120.0
+"""A seeding clone moves a whole history, once per board, from one local
+directory to another beside it — no network in it at all, so the number is
+patience against a very large repo and never a network budget."""
+
+
+def at(board_dir: Path) -> Path | None:
+    """The board's repo if somebody has created it — never creates one."""
+    repo = board_dir / REPO
+    return repo if (repo / "HEAD").is_file() else None
+
+
+def ensure(board_dir: Path) -> Path:
+    """Create the bare repo, refusal config included. Safe to run twice: `git
+    init` on an existing repository re-reads it and moves nothing, and setting
+    the same config value again is idempotent — so two racing first pushes both
+    land on the same repo instead of needing a lock here."""
+    repo = board_dir / REPO
+    run.must(
+        "init", "--bare", "--initial-branch=master", str(repo),
+        why=f"cannot create the board's repository at {repo}",
+    )
+    run.must("config", "receive.denyDeletes", "true", cwd=repo)
+    run.must("config", "receive.denyNonFastForwards", "true", cwd=repo)
+    return repo
+
+
+LEGACY_MIRROR = "mirror.git"
+"""What §16's FIRST amendment left on disk — `<root>/<board>/mirror.git`, the
+bare read-only clone of the declared forge that used to be the host's only git.
+The name is kept here, in the module that replaced it, and nowhere else: the
+mirror is retired, and the one thing still owed to it is the history it holds.
+"""
+
+
+def adopt(board_dir: Path) -> Path | None:
+    """The board's repo, seeding it from a retired `mirror.git` if that is all
+    this board has. Never creates an EMPTY repo — that is `ensure`'s job, and
+    only a write-credentialed push may ask for it.
+
+    §16's "On-disk" paragraph, implemented: production hosts carry a populated
+    `mirror.git` today, and the reversal must not lose the history in it. So a
+    board with a mirror and no `repo.git` gets one local `git clone --bare
+    mirror.git repo.git` — on-disk, no network, cheap — and the mirror
+    directory is then REMOVED, which is the whole point of not promoting it in
+    place: `--mirror`'s fetch refspec means *make local match the forge,
+    prunes included*, and a truth-holder configured to erase itself is not a
+    truth-holder. `clone --bare` copies the refs and configures none of that.
+
+    It runs on the READ path (`http/repos.py`), which is the one place that
+    breaks the "a read never writes" rule on purpose and only here: this is a
+    MIGRATION of a history the host already possesses, not a directory
+    conjured by a stranger's question — nothing is created for a board that
+    holds neither repo, so an unknown name still leaves the disk untouched. It
+    happens at most once per board, ever, because the mirror is gone after it.
+
+    A failed clone leaves the mirror alone and answers None: a migration that
+    half-ran and then deleted its source would be the one unrecoverable
+    outcome here.
+    """
+    found = at(board_dir)
+    if found is not None:
+        return found
+    legacy = board_dir / LEGACY_MIRROR
+    if not (legacy / "HEAD").is_file():
+        return None
+    repo = board_dir / REPO
+    result = run.git("clone", "--bare", str(legacy), str(repo), timeout=CLONE_TIMEOUT)
+    if not result.ok or at(board_dir) is None:
+        return None
+    run.must("config", "receive.denyDeletes", "true", cwd=repo)
+    run.must("config", "receive.denyNonFastForwards", "true", cwd=repo)
+    # `clone --bare` inherits an `origin` pointing at the mirror we are about
+    # to delete — a remote that names a directory that no longer exists is a
+    # lie a later `git fetch` would trip over. The outbound remote is `forge`
+    # (`gitwork/onward.py`), added by the owner; nothing here needs an origin.
+    run.git("remote", "remove", "origin", cwd=repo)
+    rmtree(legacy, ignore_errors=True)
+    return repo

taskops/gitwork/onward.py

@@ -0,0 +1,168 @@
+"""The outbound leg — `repo.git` → the declared forge, after a push lands.
+
+§16 ("The host becomes the remote") inverted the forge relationship: the host
+holds the history and GitHub is a full COPY of it. So a push that lands here
+is pushed onward, and `mirror.py`'s pull direction retires — one direction on
+each leg (worktree → host, host → forge), which is what keeps §11's
+replication ban intact through the reversal.
+
+**Best effort, and never a gate — in outcome AND in time.** The client's push
+has already landed; nothing here may fail it, revert it, or make it wait. The
+budget is `remote.py::PUSH_TIMEOUT`, reused rather than re-decided, because it
+is the same question with the same answer ("a push is never a gate, so it may
+never cost more than a moment"), and the work runs on a BACKGROUND thread
+started after the response is on the wire: inline, a forge that hangs would
+hold the receive door's thread and delay the very `git push` that already
+succeeded — the client would experience the mirror as a ten-second gate, which
+is the one thing it must never be.
+
+**Two pushes racing is normal and needs no lock.** The refspec is the whole
+`refs/heads/*`, so a later push SUBSUMES an earlier one: whichever thread runs
+last leaves the forge holding everything both of them had, and an interleaved
+pair does the same work twice at worst. What does need care is the REPORT,
+which is why `store/mirroring.py` guards its upsert by timestamp — threads may
+finish out of order and an older failure must not overwrite a newer success.
+
+**Failure is visible, never swallowed.** Every outcome is recorded as the
+board's `mirror` fact (`store/mirroring.py` argues that channel: the board
+payload, not a log line), including the one an owner is most likely to hit —
+no credential on the host. Nothing here raises into the door.
+
+**The credential is the OWNER's, and this module knows nothing about it**
+(§19.2, the escalation). The address is a remote named `forge` inside
+`repo.git`, configured by the owner by hand:
+
+    git -C <root>/<board>/repo.git remote add forge git@github.com:owner/name.git
+
+backed by a WRITE deploy key in the host user's ssh config. It is deliberately
+NOT derived from the declared fact the way `mirror.py::_url` derived its
+anonymous https address: an https push would need a token, and a token is what
+§11 bans. A forge declared with no remote configured is the "no key" case and
+reads as a failure naming that exact command — an owner who declines the
+escalation is told so on every board read, and the read side stays whole.
+
+**Fast-forward only, never a force, never a prune.** `--mirror` is the refspec
+that would have made this one line, and it DELETES on the far side; a force
+would rewrite there. The host demands neither of itself (`bare.py` writes
+`receive.denyDeletes` into its own config) and does not do to the forge what it
+refuses for itself. A branch pruned on GitHub simply comes back on the next
+push, which is the whole point of the chapter.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from pathlib import Path
+from threading import Thread
+
+from . import run, bare, remote
+from .. import _clock
+from ..core import forge as forges
+from ..store import mirroring
+from ..verbs import project
+from .._errors import TaskopsError
+from ..store.stores import Stores
+
+__all__ = ["REMOTE", "REFSPEC", "configured", "push", "onward", "after_receive"]
+
+REMOTE = "forge"
+"""The remote name inside `repo.git`. `origin` is deliberately not reused: on
+the host, `repo.git` has no origin — it was created empty by a client's push
+(`bare.py`) — and a name that says what the far side IS cannot be confused
+with the worktree's own remote by an owner reading `git remote -v`."""
+
+REFSPEC = "refs/heads/*:refs/heads/*"
+"""Both sides spelled out, for `remote.py::push`'s measured reason (a
+one-sided refspec is resolved through `push.default`), and the whole namespace
+because the host is the source: a card branch that landed here belongs on the
+forge whether or not this particular push mentioned it. Heads only — tags are
+not what this chapter is about, and a tag is a publication."""
+
+NO_REMOTE = (
+    "nothing was pushed onward: board {board!r} declares the forge {forge} and "
+    "this host has no remote named {remote!r} in its repo.git. That credential is "
+    "the owner's explicit act (ARCHITECTURE §19.2) — mint a WRITE deploy key for "
+    "the repo, install it for the host user, then run: git -C {repo} remote add "
+    "{remote} git@{host}:{slug}.git"
+)
+"""The failure an owner is most likely to meet, and the only one whose words are
+ours rather than git's: git cannot say "you have not decided yet". It leads with
+the consequence and ends with the exact command, because it is read on a board
+payload where the tail is what a length cap would cut."""
+
+
+def configured(repo: Path) -> str:
+    """The owner's outbound address, or "" — the one question, asked once."""
+    result = run.git("remote", "get-url", REMOTE, cwd=repo)
+    return result.out if result.ok else ""
+
+
+def push(repo: Path) -> tuple[bool, str]:
+    """`(ok, detail)` — never raises, whatever the network or git does.
+
+    `run.git` RAISES on a timeout (right for a worker, wrong for a leg nobody
+    is waiting on), so the catch is part of the contract exactly as it is in
+    `mirror.py`. `detail` is git's own words, because a mirror failure is read
+    by the owner who has to fix it: "Permission denied (publickey)" IS the
+    instruction, and a sentence of ours in its place would be a guess.
+    """
+    try:
+        result = run.git("push", REMOTE, REFSPEC, cwd=repo, timeout=remote.PUSH_TIMEOUT)
+    except TaskopsError as err:  # timeout, or no git at all
+        return False, str(err)
+    if result.ok:
+        return True, ""
+    said = (result.err or result.out).strip()
+    return False, said or f"git push exited {result.code} and said nothing"
+
+
+def onward(board_dir: Path, stores: Stores, board: str = "") -> dict[str, Any] | None:
+    """Push onward and record what happened. None means nothing was attempted.
+
+    A board with NO declared forge returns None before touching git: no
+    mirroring, no attempt, no error — §16's "not a fault", and the state every
+    board is born in. No `repo.git` is the same answer: there is nothing to
+    copy yet.
+    """
+    fact = project.forge(stores)
+    if fact is None:
+        return None
+    repo = bare.at(board_dir)
+    if repo is None:
+        return None
+    where = configured(repo)
+    if not where:
+        ok, detail = False, NO_REMOTE.format(
+            board=board or board_dir.name,
+            forge=forges.label(fact),
+            remote=REMOTE,
+            repo=repo,
+            host=fact["host"],
+            slug=fact["repo"],
+        )
+    else:
+        ok, detail = push(repo)
+    at = _clock.now()
+    try:
+        mirroring.record(stores.live, forges.label(fact), ok=ok, detail=detail, at=at)
+    except TaskopsError:  # a live store this thread cannot write is not the push's problem
+        return None
+    return {"forge": forges.label(fact), "ok": ok, "at": at, "detail": detail}
+
+
+def after_receive(board_dir: Path, stores: Stores, board: str = "") -> Thread | None:
+    """Start the outbound leg for a push that just landed, or return None.
+
+    The thread is a daemon: a host shutting down must not wait on a forge, and
+    the next push repeats the whole refspec anyway, so an interrupted mirror
+    costs nothing but a report that stays honest about the last one that ran.
+    The forge fact is asked HERE too, so a board without one starts no thread
+    at all — "no attempt" is a promise about the process table as well.
+    """
+    if project.forge(stores) is None:
+        return None
+    thread = Thread(
+        target=onward, args=(board_dir, stores, board), name="taskops-mirror", daemon=True
+    )
+    thread.start()
+    return thread