Merge origin/main into feat/evict-closed-issues

Three doc conflicts, all unions: the script lists in AGENTS.md and the runner
gain both close.py and evict.py, and the sync skill keeps both the closing and
the evicting sections. Rule 4 of the runner is rewritten once to carry both
halves — closing is now a script it may run on named ids, retitling and remote
deletion stay forbidden, and the two allowed local deletions (push's own, and
eviction) are listed together.

skills/auth/SKILL.md

@@ -32,13 +32,37 @@ So:
 3. **One login:** propose it; confirm before writing.
 4. **Several logins:** `AskUserQuestion` with each login's `name`, `user`, and
    `url` so the operator's choice is unambiguous. Never decide for them.
-5. Merge the chosen name into `.claude/settings.local.json` under `env`
-   (do not clobber other keys):
+5. Merge the chosen name into the **project root's**
+   `.claude/settings.local.json` under `env` (do not clobber other keys):
    ```json
    { "env": { "GITEA_LOGIN": "<chosen-name>" } }
    ```
+   **In a git worktree, write it to the main checkout, never to the worktree.**
+   A worktree is deleted when the branch is done, taking a pin written into it
+   with it, and one repository with two pins is one repository with two
+   identities. Both the guard and the scripts already reach the main checkout's
+   pin from inside any worktree — so there is nothing to pin a second time.
+   `git rev-parse --path-format=absolute --git-common-dir` names the `.git` to
+   write beside.
 6. Done — it is live. The guard resolves the pin from the file on the next
-   `tea` call; no restart needed. Tell the operator which login is now pinned.
+   `tea` call; no restart needed. Tell the operator which login is now pinned,
+   and which file it went in.
+
+## Where the pin is looked for
+
+One search order, written once in `scripts/pin.py` and imported by both the
+`tea-guard` hook and the sync/wiki transport — they cannot disagree about a
+directory, and a test asserts neither keeps a copy of the walk.
+
+`$CLAUDE_PROJECT_DIR`, then the caller's hint (the hook passes the Bash call's
+`cwd`), then the current directory. Each is searched up its parent chain; only
+if that finds nothing does the search cross into the main working tree of a
+linked worktree, via `gitdir:` in the `.git` file. The plugin's own directory
+is never a source — a plugin pointed at somebody else's project must take the
+identity from that project, not from where it happens to be installed.
+
+If a script reports "no login pinned", that is the honest answer: nothing was
+found anywhere on that order. Pin one — at the project root.
 
 ## Identity-safety rules
 

skills/auth/scripts/pin.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+pin.py — where the operator's Gitea login pin is, and how it is found.
+
+**The search order lives here and nowhere else.** The `tea-guard` hook imports
+this module; so does the transport every sync and wiki script runs on. Two
+copies of the order is exactly how a git worktree came to have a working hook
+and a dead transport in the same directory: `tea` resolved the login, the
+scripts said "no login pinned", and the error told the operator to pin what was
+already pinned.
+
+Not a command — a lookup. Stdlib only, no subprocess, no network: a PreToolUse
+hook runs before every Bash call and must not fork a process to answer this.
+
+The pin is a file the OPERATOR owns and `/tea:auth` writes:
+
+    <project root>/.claude/settings.local.json  ->  env.GITEA_LOGIN
+
+## Search order
+
+Start directories, in order, first hit wins:
+
+    1. $CLAUDE_PROJECT_DIR   the project Claude Code was started on, when set
+    2. an explicit hint      the hook passes the Bash tool's cwd; scripts pass
+                             nothing and go straight to 3
+    3. the current directory
+
+Each start directory is searched the same way:
+
+    a. up the parent chain, from the directory itself to the filesystem root
+    b. then, for each LINKED WORKTREE seen on that chain, up the parent chain
+       of that repository's main working tree
+
+(b) is the whole point of this module. A worktree is a *sibling* of the main
+checkout, not a descendant, so `.claude/settings.local.json` — untracked, and
+therefore only ever in the main checkout — is not on the parent chain of (a).
+Git knows the two trees are one repository: a worktree's `.git` is a FILE
+holding `gitdir: <path>`, and `<path>/commondir` points back at the shared
+`.git`. `git rev-parse --git-common-dir` answers the same question by forking;
+this reads the files.
+
+## Why the search does not start at __file__
+
+Deliberate asymmetry with `issue.store_root` and `_gitea.PAYLOAD_ROOT`, which
+*are* anchored on their own module's location. Two different questions:
+
+    where does this installation keep its files   a fact about the plugin
+    whose login does this project run under       a fact about the project
+
+A plugin installed outside any repository and pointed at somebody else's tree
+must answer the second one from the tree it was pointed at. Anchoring the pin
+on `__file__` would make the plugin's own directory an identity source, which
+is how a checkout ends up acting under a login nobody chose for it. So the
+search runs from the working directory upward — and reaches a worktree's main
+checkout by asking git, not by walking somewhere else.
+
+Finding nothing is a real answer: `(None, None)` means there is no pin, and the
+caller says so. This module never guesses a login.
+"""
+import json
+import os
+
+SETTINGS_PARTS = (".claude", "settings.local.json")
+ENV_KEY = "GITEA_LOGIN"
+PROJECT_DIR_ENV = "CLAUDE_PROJECT_DIR"
+
+
+def settings_path(root):
+    """The pin file for a project root. The one place this path is spelled."""
+    return os.path.join(root, *SETTINGS_PARTS)
+
+
+def read_pin(path):
+    """The login in a settings file, or None.
+
+    Unreadable, not JSON, no `env`, empty string — all the same answer. A
+    broken file is not a login and is not worth a traceback in a hook."""
+    try:
+        with open(path) as f:
+            value = (json.load(f).get("env") or {}).get(ENV_KEY)
+    except Exception:
+        return None
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def parents(start):
+    """`start` and every ancestor of it, up to the filesystem root."""
+    d = os.path.abspath(start)
+    while True:
+        yield d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return
+        d = parent
+
+
+def gitdir_of(d):
+    """The private git directory `d/.git` points at, or None.
+
+    Only a `.git` FILE is a pointer; in an ordinary clone `.git` is a
+    directory and there is nothing to follow."""
+    p = os.path.join(d, ".git")
+    if not os.path.isfile(p):
+        return None
+    try:
+        with open(p) as f:
+            head = f.read(4096)
+    except OSError:
+        return None
+    for line in head.splitlines():
+        line = line.strip()
+        if line.startswith("gitdir:"):
+            target = line[len("gitdir:"):].strip()
+            if not target:
+                return None
+            if not os.path.isabs(target):
+                target = os.path.join(d, target)
+            return os.path.abspath(target)
+    return None
+
+
+def main_worktree(d):
+    """If `d` is a linked worktree, the main working tree of its repository.
+
+    `<worktree>/.git` -> `<main>/.git/worktrees/<name>`, whose `commondir`
+    file holds a path to `<main>/.git`; the main working tree is its parent.
+    The `.git` basename check keeps this to worktrees: a submodule's `.git`
+    is a pointer too, but it points into `<super>/.git/modules/…`, and the
+    tree it belongs to is already on the parent chain."""
+    gitdir = gitdir_of(d)
+    if not gitdir or not os.path.isdir(gitdir):
+        return None
+    common = gitdir
+    marker = os.path.join(gitdir, "commondir")
+    if os.path.isfile(marker):
+        try:
+            with open(marker) as f:
+                rel = f.read().strip()
+        except OSError:
+            rel = ""
+        if rel:
+            common = os.path.abspath(os.path.join(gitdir, rel))
+    if os.path.basename(common) != ".git":
+        return None
+    root = os.path.dirname(common)
+    if root and os.path.isdir(root) and root != os.path.abspath(d):
+        return root
+    return None
+
+
+def search(start):
+    """(login, path) for one start directory: the parent chain, then the main
+    checkout of any worktree met on it. (None, None) when there is no pin.
+
+    The chain comes first and always wins, so the worktree branch can only
+    ever find a pin that walking up would not have found at all."""
+    hops = []
+    for d in parents(start):
+        login = read_pin(settings_path(d))
+        if login:
+            return login, settings_path(d)
+        root = main_worktree(d)
+        if root and root not in hops:
+            hops.append(root)
+    for root in hops:
+        # One level of indirection, never two: a main checkout is not itself a
+        # linked worktree, so this loop cannot chain and cannot cycle.
+        for d in parents(root):
+            login = read_pin(settings_path(d))
+            if login:
+                return login, settings_path(d)
+    return None, None
+
+
+def start_dirs(hint=None):
+    """The ordered, deduplicated start directories.
+
+    `hint` is the caller's own idea of where the work is happening — the hook
+    passes the `cwd` from its payload, which is the directory the Bash command
+    will actually run in. A script has no payload and passes nothing."""
+    try:
+        cwd = os.getcwd()
+    except OSError:      # cwd deleted out from under us
+        cwd = None
+    out = []
+    for d in (os.environ.get(PROJECT_DIR_ENV), hint, cwd):
+        if not d:
+            continue
+        d = os.path.abspath(d)
+        if d not in out:
+            out.append(d)
+    return out
+
+
+def find_pin(hint=None):
+    """(login, path) for the first start directory that has a pin, else
+    (None, None). The entry point; everything above is its parts."""
+    for start in start_dirs(hint):
+        login, path = search(start)
+        if login:
+            return login, path
+    return None, None

skills/issue/SKILL.md

@@ -118,7 +118,9 @@ the table. Checkboxes are the exception — use `issue_ac.py`, below.
 
 If the issue is synced (`origin: gitea`), the file is a working copy: your edit
 is local until you run `push.py --update` from `/tea:sync`, and that push
-**deletes the file** once Gitea has it. Nothing tracks drift, and with one copy
+**deletes the file** once Gitea has it. Closing one of those is `close.py` from
+`/tea:sync` — it moves the state on both sides in a single run; editing
+`state:` here alone would only ever tell this machine. Nothing tracks drift, and with one copy
 at a time there is little to track — a file that is still here has not been
 pushed. Get it back with `pull.py <n>`; the slug does not change.
 

skills/sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sync
-description: Move issues between the local store and Gitea — pull issues into tmp/issues/, push local issues up, post comments. Load when the user asks to fetch/read a Gitea issue, publish an issue, list what exists in the tracker, or comment on one. Working with an issue's content (writing, grepping, validating, dependency graph) is /tea:issue and needs no network.
+description: Move issues between the local store and Gitea — pull issues into tmp/issues/, push local issues up, post comments, close and reopen them. Load when the user asks to fetch/read a Gitea issue, publish an issue, list what exists in the tracker, comment on one, or close/reopen one. Working with an issue's content (writing, grepping, validating, dependency graph) is /tea:issue and needs no network.
 ---
 
 # /tea:sync — the bridge between the local store and Gitea
@@ -32,16 +32,22 @@ index.
 ## Scripts
 
 In `<skill-base-dir>/scripts/`. None of them take `--login`: they resolve the
-operator's pin from `.claude/settings.local.json` themselves, the same source
-the `tea-guard` hook reads. No pin → exit with a pointer to `/tea:auth`.
+operator's pin from `.claude/settings.local.json` through
+`skills/auth/scripts/pin.py` — the same *function* the `tea-guard` hook calls,
+not merely the same file, so a directory where `tea` works is a directory where
+these work. That includes a **git worktree**, whose untracked pin sits in the
+main checkout: the search crosses to it through the `gitdir:` in `.git`, and
+there is nothing to pin a second time. No pin anywhere → exit with a pointer to
+`/tea:auth`.
 
 | Script | What it does |
 |---|---|
-| `remote.py [--state] [--label] [--milestone] [-q TEXT]` | discovery: one line per Gitea issue to stdout, writes nothing |
-| `pull.py <key…>` or `pull.py --milestone M \| --label L \| -q TEXT` | Gitea → `tmp/issues/<id>.md`, plus `<id>.comments.md` when the thread is not empty |
+| `remote.py [--state] [--label] [--milestone] [-q TEXT] [--limit N]` | discovery: one line per Gitea issue to stdout, writes nothing; `--limit` caps the **listing** (default 30) |
+| `pull.py <key…>` or `pull.py --milestone M \| --label L \| -q TEXT [--limit N]` | Gitea → `tmp/issues/<id>.md`, plus `<id>.comments.md` when the thread is not empty; follows dependencies by default (`--no-deps` to stop); `--limit` caps what is **stored** (default 100) |
 | `push.py [id…] [--update] [--dry-run]` | local → Gitea; validates first, **deletes the local file on success** and prints where it lives now |
 | `evict.py [id…] [--dry-run]` | refresh `state:` from Gitea, then evict the issues it reports closed; `origin: local` is never asked about and never removed |
 | `comment.py <id> --file F \| --body TEXT [--edit N]` | post or edit a comment, then refetch the thread |
+| `close.py <id…> [--reopen] [--dry-run]` | set `state` in Gitea and in the local copy with it; explicit ids only, no bulk filter |
 | `labels.py [--dry-run] [--fix]` | bootstrap the canonical `type/*` + `severity/*` set in a repo; exact names left alone, lookalikes reported, drift fixed only with `--fix` |
 | `map.py`, `_gitea.py` | the two layers the commands import — not commands |
 
@@ -89,7 +95,7 @@ python3 <skill-base-dir>/scripts/pull.py 42
 python3 <skill-base-dir>/scripts/pull.py --milestone 6          # id or title
 python3 <skill-base-dir>/scripts/pull.py --label type/bug --state all
 python3 <skill-base-dir>/scripts/pull.py -q sqlc --limit 20
-python3 <skill-base-dir>/scripts/pull.py 40 --deps              # follow dependencies
+python3 <skill-base-dir>/scripts/pull.py 40 --no-deps           # this issue only
 ```
 
 Do not loop over numbers to pull a group — pass the filter. The list endpoint
@@ -115,13 +121,55 @@ already on disk is refreshed either way — the local copy learns it was closed
 instead of staying open forever. Key mode is exempt: `pull.py 1` fetches a
 closed issue as always, because an address is not a bulk read.
 
+**`--limit N` bounds the write, not the selection.** N is how many issues this
+run leaves in the store — written, or left in place by `--cached`. Closed ones
+that were enumerated and thrown away do not spend it, so `--limit 20` over a
+milestone whose first 30 issues are closed still writes 20, as long as 20 open
+ones are there to write. Pagination follows the budget rather than the other way
+round:
+
+| | |
+|---|---|
+| budget full | the next page is never requested |
+| pages run out | fewer than N, and that is the honest answer |
+| filter matches almost only closed issues | at most 4× the pages N would need if nothing were dropped, then a warning on stderr and a short answer — raising `--limit` raises that ceiling too |
+| dependencies | outside the count: a blocker is followed because a stored issue named it, not because the filter selected it — so `--limit 20` can leave more than 20 files behind |
+
+`remote.py --limit` means something else, deliberately: it caps the **listing**,
+closed issues included. It writes nothing, so there is no write for a limit to
+bound — enumeration is its whole job.
+
 **Comments come with every pull** — there is no flag. An issue that has a
 thread gets `tmp/issues/<id>.comments.md` beside it, in key mode and in filter
 mode alike, and the issue's output line says how many. An issue with none
 costs nothing: the count arrives in the list payload, so no request is made
 and no file is written — and a file left over from a thread that has since
 been emptied is deleted. `--cached` skips the thread along with the body, so a
-skipped issue makes no request at all.
+skipped issue makes one request for its links and no other.
+
+**Dependencies come with every pull too, and this one costs.** A pull answers
+with the unit of work — the issue and what blocks it — so `depends:` is filled
+from Gitea's native graph and every blocker is pulled as well, recursively, down
+to `--depth` (default 3). It has to come from the native graph: the body's
+`## Depends on` section holds slugs, never `#N`, so there is no edge to recover
+from the text. `--no-deps` turns off both halves. `--deps` is still accepted and
+does nothing — it names the default.
+
+| | requests |
+|---|---|
+| every issue that lands in the store | **+1** — `GET …/issues/{n}/dependencies`, fetched once and used twice (fills `depends:`, steers the walk) |
+| every blocker the selection did not already carry | **+1** to fetch it, then its own links, until `--depth` |
+| a closed issue filter mode drops | 0 — nothing was stored, so there is no unit of work to complete |
+| `--milestone X` over 50 open issues | 1 list request + 50, plus a pair per outside blocker — it used to be 1 |
+| the same with `--no-deps` | 1 |
+
+**A blocker the filter did not select still lands in the store, deliberately.**
+`--milestone X` can leave an issue from milestone Y on disk; `--label` can leave
+an unlabelled one. It is there because a stored issue names it, not because it
+matched. The exception is a closed blocker: closed is not a unit of work, filter
+mode drops it like any other closed issue, and the `depends:` edge to it goes
+with it — nothing is left pointing at a file that is not there. Key mode
+(`pull.py 42`) has no such rule and stores it.
 
 Two traps this handles for you:
 
@@ -234,7 +282,7 @@ accumulate them however many round trips it makes, and why a body that somehow
 gained two is cleaned on the next pull.
 
 `depends:` survives the same round trip through Gitea's native links (below):
-push writes them, `pull.py --deps` reads them back, and the ledger turns the
+push writes them, every `pull.py` reads them back, and the ledger turns the
 numbers into the slugs they had here.
 
 Before anything is sent, `/tea:issue`'s validator runs (exactly one `type/*`,
@@ -254,7 +302,7 @@ The two directions are symmetric, and they use the same endpoint:
 | | direction | endpoint |
 |---|---|---|
 | `push.py` | `depends:` → native links | `POST …/issues/{n}/dependencies` |
-| `pull.py --deps` | native links → `depends:` | `GET …/issues/{n}/dependencies` |
+| `pull.py` (default; `--no-deps` off) | native links → `depends:` | `GET …/issues/{n}/dependencies` |
 
 The POST body is Gitea's `IssueMeta` — `{"index", "owner", "repo"}` naming the
 **blocker**, posted to the **blocked** issue's endpoint ("make the issue in the
@@ -299,6 +347,10 @@ decision, not a migration. A color or `exclusive` that drifted is printed, and
 changed only under `--fix`. Running it twice creates nothing. `tech/*` and
 `comp/*` are open-ended by design and stay push-created.
 
+Labels belong to the repository, not to any issue, so this one runs on a
+checkout with no store and leaves it that way — nothing here reads `tmp/issues/`
+and nothing creates it. The request bodies go to `tmp/payload/` (below).
+
 A milestone must already exist in the repo — push attaches, it does not create.
 
 `branch:` is Gitea's `ref`, the branch the work actually lives on. Push fills
@@ -309,6 +361,60 @@ a git repo no `ref` is sent and a warning names the issues that went up without
 one. Reading the branch is the only thing these scripts ask git for — they
 never check out, create, or write anything.
 
+The branch comes from the **current directory**, so run `push.py` from the tree
+the work is on. In a git worktree that is the worktree, and it is now also
+where the pin resolves from: the old workaround for the pin — run the scripts
+with cwd in the main checkout — sent the main checkout's branch as `ref`, which
+is the one thing `branch:` exists to record.
+
+## Closing and reopening
+
+```bash
+python3 <skill-base-dir>/scripts/close.py wire-sqlc-appclick      # by slug
+python3 <skill-base-dir>/scripts/close.py 42 '#43'                # by number
+python3 <skill-base-dir>/scripts/close.py --reopen 42
+python3 <skill-base-dir>/scripts/close.py --dry-run 42 43         # no request at all
+```
+
+`close.py` is the only supported way to move `state:`. Never hand-roll
+`tea api -X PATCH -d '{"state":"closed"}' repos/OWNER/REPO/issues/N`: it spells
+out the owner, the repo and the request body — the three things this layer
+exists to hide — and it needs a `Bash(tea api *)` permission that also covers
+`-X DELETE` on the repository.
+
+**State only.** The payload is `{"state": …}` and nothing else — no title, no
+body, no labels, no milestone. Closing is not an edit; editing is `pull.py` →
+change → `push.py --update`.
+
+**Explicit ids only.** There is no `--milestone` and no `--label`: which issues
+are finished is a judgement about content, and this script only carries one
+out, one named id at a time. Deleting an issue is out of scope too — Gitea can,
+and it is not an operation of this workflow.
+
+What may be named, and what happens to the local copy:
+
+| named | resolved through | local file |
+|---|---|---|
+| a slug with a file on disk | its `gitea:` field | `state:` rewritten, `synced:` refreshed |
+| a slug whose file push dropped | `.remote.json` | none to write — say so and move on |
+| `42`, `#42`, `owner/repo#42`, a URL | the key itself; the ledger supplies the slug | rewritten when a file of that slug is there |
+| a slug with `origin: local` | — | **refused**: it is not in the tracker, and the error names the id |
+
+The local file is written only after the tracker has confirmed *this* write: an
+object carrying the very number that was PATCHed, in the state that was asked
+for. A non-2xx, a `tea` that would not run, an answer for another issue, a 200
+that still says `open` — the run stops and the file is byte for byte what it
+was. `--dry-run` prints the same lines and makes no request at all, so it needs
+no pinned login.
+
+Gitea refuses to close an issue that its own dependency graph still blocks. The
+refusal arrives as a non-2xx with the tracker's own words: close the blockers
+first, or unlink them in the web UI.
+
+The index is rebuilt when at least one local file changed, so `INDEX.md` never
+outlives the state it reports. Nothing is deleted here — unlike a push, a close
+leaves the working copy where it is.
+
 ## Evicting what the tracker says is closed
 
 ```bash
@@ -371,7 +477,7 @@ so there is no reason to start before every answer is in.
 | `labels` | `labels[]` | names both ways; ids only on write |
 | `assignees` | `assignees[]` | logins |
 | `milestone` | `milestone.title` | resolved to an id on write |
-| `depends` | native links | slugs here, `IssueMeta` there; push writes them, `pull --deps` reads them |
+| `depends` | native links | slugs here, `IssueMeta` there; push writes them, every pull reads them (`--no-deps` opts out) |
 | — | `ref` | lands in `branch:`; sent only when non-empty |
 | — | `number`, `html_url` | lands in `gitea:` / `url:` |
 
@@ -406,6 +512,13 @@ precisely so the mechanism this section rules out is not needed.
 
 ## Rich payloads for everything else
 
+Every body these scripts send is written to `<repo>/tmp/payload/<name>.json`
+first and passed as `-d @file`, then kept for a retry or a look at what actually
+went up. One gitignored directory for all of them, chosen by the transport and
+not by the caller. **It is not a store**: nothing in it is anybody's only copy,
+and it is never `tmp/issues/` — a command that touches no issue must not leave
+an issue store behind.
+
 Comments and issues are wrapped by the scripts above. For **other** entities
 (pulls, releases, PATCHing something these scripts do not cover), entity
 subcommands like `tea pulls create` hang on a large or formatted body — an

skills/sync/scripts/_gitea.py

@@ -7,8 +7,10 @@ query quirks. It does NOT know what an issue is: no sections, no acceptance
 criteria, no type taxonomy. Payload shapes come from map.py; the domain model
 lives one layer further out in skills/issue/scripts/issue.py.
 
-Login: resolved from .claude/settings.local.json (env.GITEA_LOGIN), walking up
-from CWD — the same file /tea:auth writes and the tea-guard hook reads. No
+Login: the operator's pin from .claude/settings.local.json (env.GITEA_LOGIN).
+Where that file is searched for is NOT written here — skills/auth/scripts/pin.py
+owns the search order, and the tea-guard hook imports the same module, so `tea`
+and the scripts can never disagree about which login a directory runs under. No
 script here accepts a login argument: the operator's pin is the only identity
 they will use. No pin -> exit with a pointer to /tea:auth.
 
@@ -18,6 +20,13 @@ it is transport bookkeeping, not domain data — the domain never reads any of
 it, and losing the map still costs a re-pull and not information: the slug it
 records also travels in the issue body as `<!-- tea:id … -->` (map.py), so a
 pull rebuilds the entry from the tracker. See `rebuild_map`.
+
+Request bodies go to tmp/payload/, which is this module's own scratchpad and
+NOT a store: nothing in it is anybody's only copy, and writing one must never
+materialize tmp/issues/ on a checkout that has none. Bootstrapping labels
+touches no issue at all — it used to leave a store behind anyway, because the
+request file had nowhere else to live. One directory, every caller, resolved
+from this file the way the two domains resolve theirs.
 """
 import datetime
 import json
@@ -27,9 +36,33 @@ import re
 import sys
 import urllib.parse
 
-PAYLOAD_DIR = ".payload"
 REMOTE_MAP = ".remote.json"
 
+# How far past the ideal page count a `keep`-bounded listing may scan before it
+# gives up (see list_issues). The ideal is what `limit` would need if every
+# payload counted; the slack pays for the ones that do not. It is a bound on
+# requests, deliberately small: "fetch until N are kept" without one is "fetch
+# the whole tracker" on any repo whose filter matches mostly closed issues.
+PAGE_SLACK = 4
+
+# --------------------------------------------------------------------------
+# where request bodies land
+# --------------------------------------------------------------------------
+# Anchored on THIS FILE, like issue.store_root and page.store_root, so every
+# caller — sync, wiki, whatever comes next — writes to one directory whatever
+# it was invoked from. Visible and top-level under tmp/, not a dotdir hidden
+# inside somebody's store, because a scratchpad that looks like store contents
+# is how this went wrong the first time. `tmp/` is already gitignored.
+
+PAYLOAD_PARTS = ("tmp", "payload")
+
+# `.git` is a directory in a normal clone and a FILE in a worktree — hence
+# exists(), not isdir(). AGENTS.md is the fallback for a plugin copied out of
+# git; the agents-sync hook only ever puts one at a repository root.
+REPO_MARKERS = (".git", "AGENTS.md")
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
 
 def die(msg, code=1):
     sys.stderr.write("%s: %s\n" % (os.path.basename(sys.argv[0]), msg))
@@ -44,32 +77,64 @@ def now_iso():
     return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-# --------------------------------------------------------------------------
-# login
-# --------------------------------------------------------------------------
-
-def find_pin(start_dir=None):
-    """Walk up from start_dir; return the login from the first
-    .claude/settings.local.json carrying a non-empty env.GITEA_LOGIN."""
-    d = os.path.abspath(start_dir or ".")
+def repo_root(start):
+    """Nearest ancestor of `start` (inclusive) carrying a repo marker, or None."""
+    d = os.path.abspath(start)
     while True:
-        p = os.path.join(d, ".claude", "settings.local.json")
-        if os.path.isfile(p):
-            try:
-                with open(p) as f:
-                    v = (json.load(f).get("env") or {}).get("GITEA_LOGIN")
-                if isinstance(v, str) and v.strip():
-                    return v.strip()
-            except Exception:
-                pass
+        if any(os.path.exists(os.path.join(d, m)) for m in REPO_MARKERS):
+            return d
         parent = os.path.dirname(d)
         if parent == d:
             return None
         d = parent
 
 
+def payload_root(start=None):
+    """Absolute path of the request-body scratchpad.
+
+    `start` overrides the anchor so the resolution can be exercised against a
+    scratch tree. Outside a repository, cwd gets a turn, then the cwd-relative
+    location stands — made absolute so an error can name the directory it
+    really wrote to."""
+    for anchor in ([start] if start is not None else [_HERE, os.getcwd()]):
+        root = repo_root(anchor)
+        if root:
+            return os.path.join(root, *PAYLOAD_PARTS)
+    return os.path.abspath(os.path.join(*PAYLOAD_PARTS))
+
+
+PAYLOAD_ROOT = payload_root()
+
+
+# --------------------------------------------------------------------------
+# login
+# --------------------------------------------------------------------------
+# Borrowed from the identity layer, not reimplemented: `pin.find_pin` is the
+# single written copy of the search order, and the tea-guard hook calls the
+# same function. When the two had a copy each, a git worktree got a hook that
+# resolved the pin and a transport that did not — in the same directory.
+#
+# Note the asymmetry with PAYLOAD_ROOT above, and with issue.store_root: those
+# are anchored on their own file, this is not, and both are right. Where an
+# installation keeps its files is a fact about the installation; whose login a
+# project runs under is a fact about the project, and a plugin installed
+# outside any repository must not answer it from its own directory. See the
+# module docstring in pin.py.
+
+_AUTH_SCRIPTS = os.path.abspath(
+    os.path.join(_HERE, os.pardir, os.pardir, "auth", "scripts"))
+if _AUTH_SCRIPTS not in sys.path:
+    sys.path.append(_AUTH_SCRIPTS)
+import pin  # noqa: E402
+
+
 def require_login():
-    login = find_pin(os.getcwd())
+    """The operator's pinned login, or exit pointing at /tea:auth.
+
+    No pin found is reported as exactly that. It stays a truthful message: the
+    fix for "the pin is somewhere this search does not reach" belongs in
+    pin.py, never in a hint here that sends the operator to pin it twice."""
+    login, _ = pin.find_pin()
     if not login:
         die("no login pinned (.claude/settings.local.json env.GITEA_LOGIN). Run /tea:auth.")
     return login
@@ -80,19 +145,21 @@ def require_login():
 # --------------------------------------------------------------------------
 
 def api(login, endpoint, method="GET", payload=None, payload_name=None,
-        out_root=None, allow_fail=False):
+        allow_fail=False):
     """Call `tea api`; return parsed JSON (None on an empty body).
 
-    payload (a dict) is written to <out_root>/.payload/<name>.json and passed
-    as -d @file — the file survives the call for retries and debugging.
-    allow_fail returns None instead of exiting when the call fails."""
+    payload (a dict) is written to PAYLOAD_ROOT/<name>.json and passed as
+    -d @file — the file survives the call for retries and debugging. Where
+    that is, is not the caller's business and never was: the directory is
+    this layer's scratchpad, and the one time it was a caller's decision it
+    got pointed at the issue store. allow_fail returns None instead of
+    exiting when the call fails."""
     cmd = ["tea", "api", "--login", login]
     if method != "GET":
         cmd += ["-X", method]
     if payload is not None:
-        pdir = os.path.join(out_root or ".", PAYLOAD_DIR)
-        os.makedirs(pdir, exist_ok=True)
-        path = os.path.join(pdir, "%s.json" % (payload_name or "request"))
+        os.makedirs(PAYLOAD_ROOT, exist_ok=True)
+        path = os.path.join(PAYLOAD_ROOT, "%s.json" % (payload_name or "request"))
         with open(path, "w") as f:
             json.dump(payload, f, ensure_ascii=False, indent=2)
         cmd += ["-d", "@" + path]
@@ -114,17 +181,28 @@ def api(login, endpoint, method="GET", payload=None, payload_name=None,
         die("`tea api %s` returned non-JSON:\n%s" % (endpoint, body[:500]))
 
 
-def paginate(login, endpoint, limit=50, max_pages=40, **kw):
-    """GET a list endpoint page by page; return the concatenated list."""
+def pages(login, endpoint, limit=50, max_pages=40, **kw):
+    """GET a list endpoint page by page, yielding each page as it arrives.
+
+    A generator, because a caller whose budget is spent on what it *keeps*
+    cannot be served by a function that fetches everything first: the page after
+    the one that completed the budget must never be requested. Stop consuming
+    and no further request is made."""
     sep = "&" if "?" in endpoint else "?"
-    out = []
     for page in range(1, max_pages + 1):
         batch = api(login, "%s%spage=%d&limit=%d" % (endpoint, sep, page, limit), **kw)
         if not isinstance(batch, list) or not batch:
-            break
-        out.extend(batch)
+            return
+        yield batch
         if len(batch) < limit:
-            break
+            return  # a short page is the last one
+
+
+def paginate(login, endpoint, limit=50, max_pages=40, **kw):
+    """GET a list endpoint page by page; return the concatenated list."""
+    out = []
+    for batch in pages(login, endpoint, limit=limit, max_pages=max_pages, **kw):
+        out.extend(batch)
     return out
 
 
@@ -187,11 +265,31 @@ def matches(payload, milestone_id=None, labels=()):
 
 
 def list_issues(login, base, state="open", labels=(), query=None,
-                milestone=None, limit=100):
+                milestone=None, limit=100, keep=None):
     """Filtered issue payloads. Returns (payloads, milestone_title).
 
     One request per page, and the payload already carries the issue bodies — a
-    whole milestone costs one call per 50 issues, not one per issue."""
+    whole milestone costs one call per 50 issues, not one per issue.
+
+    `limit` counts the payloads the CALLER cares about, not the ones the server
+    returned. Without `keep` those are the same thing and this behaves as it
+    always did. With it, `keep(payload)` says whether a payload counts, pages
+    keep coming until `limit` of them have, and the returned list carries the
+    ones that did not count too — they were enumerated, and a caller that has
+    something to say about them (pull.py: "N closed, not stored") still can.
+
+    What `keep` means is the caller's business; this module only counts. Two
+    boundaries hold whatever it decides:
+
+    - **Stop at the limit.** The page after the one that completed the budget
+      is not requested — `pages` is a generator and this loop returns out of it.
+    - **Stop at the page budget.** A predicate that rejects everything must not
+      turn a bounded read into a walk of the whole tracker, so a filtered read
+      may scan at most `PAGE_SLACK` times the pages `limit` would need if every
+      payload counted. Hitting that with an unfilled budget is a warning, not a
+      silent short answer: the caller asked for N and is told it got fewer."""
+    if limit < 1:
+        die("--limit must be 1 or more, got %d" % limit)
     ms_id, ms_title = (None, None)
     if milestone is not None:
         ms_id, ms_title = resolve_milestone(login, base, milestone)
@@ -206,10 +304,25 @@ def list_issues(login, base, state="open", labels=(), query=None,
     endpoint = "%s/issues?%s" % (base, urllib.parse.urlencode(params))
 
     per_page = min(limit, 50)
-    got = paginate(login, endpoint, limit=per_page,
-                   max_pages=max(1, -(-limit // per_page)))
-    got = [p for p in got if matches(p, ms_id, labels)]
-    return got[:limit], ms_title
+    ideal = max(1, -(-limit // per_page))
+    budget = ideal if keep is None else ideal * PAGE_SLACK
+
+    got, kept, seen_pages, last_full = [], 0, 0, False
+    for batch in pages(login, endpoint, limit=per_page, max_pages=budget):
+        seen_pages += 1
+        last_full = len(batch) == per_page
+        for p in batch:
+            if not matches(p, ms_id, labels):
+                continue
+            got.append(p)
+            if keep is None or keep(p):
+                kept += 1
+                if kept >= limit:
+                    return got, ms_title
+    if keep is not None and seen_pages >= budget and last_full:
+        warn("scanned %d page(s) and stopped %d short of --limit %d — there may"
+             " be more; narrow the filter or raise --limit" % (budget, limit - kept, limit))
+    return got, ms_title
 
 
 def get_issue(login, base, number):
@@ -245,7 +358,7 @@ def native_dep_pairs(login, base, number):
     return out
 
 
-def add_dependency(login, base, number, dep_repo, dep_number, out_root=None):
+def add_dependency(login, base, number, dep_repo, dep_number):
     """Make issue `number` depend on `dep_repo#dep_number`. True on success.
 
     Confirmed against the instance's own swagger.v1.json (Gitea 1.26.1):
@@ -264,8 +377,7 @@ def add_dependency(login, base, number, dep_repo, dep_number, out_root=None):
         return False
     payload = {"index": int(dep_number), "owner": owner, "repo": name}
     got = api(login, "%s/issues/%d/dependencies" % (base, number), "POST", payload,
-              payload_name="dep-%d-%d" % (number, dep_number),
-              out_root=out_root, allow_fail=True)
+              payload_name="dep-%d-%d" % (number, dep_number), allow_fail=True)
     return got is not None
 
 
@@ -297,7 +409,7 @@ def ensure_labels(login, base, specs, root):
             continue
         payload = dict(spec, name=name)
         created = api(login, "%s/labels" % base, "POST", payload,
-                      payload_name="label-%s" % name.replace("/", "-"), out_root=root)
+                      payload_name="label-%s" % name.replace("/", "-"))
         if not created or "id" not in created:
             die("could not create label %r" % name)
         cache[name] = created["id"]

skills/sync/scripts/close.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""
+close.py — change an issue's state in Gitea, and in the local copy with it.
+
+The one regular tracker operation that used to have no script: closing. Without
+it the only way to move `state:` was a raw `tea api -X PATCH -d '{"state":
+"closed"}' repos/OWNER/REPO/issues/N`, which spells out the owner, the repo and
+the request body — the three things `_gitea.py` exists to hide — and which needs
+`Bash(tea api *)`, a permission that also covers `-X DELETE` on the repository.
+
+    close.py wire-sqlc-appclick            one issue, by slug
+    close.py wire-sqlc-appclick 42 #43     several, by slug or number
+    close.py --reopen 42                   the same thing backwards
+    close.py --dry-run 42 43               what would happen, no request at all
+
+STATE ONLY. This script sends `{"state": …}` and nothing else: no title, no
+body, no labels, no milestone. Editing an issue is `pull.py` -> edit ->
+`push.py --update`; closing it is not an edit.
+
+**What may be named.** A local slug, or a Gitea key (`42`, `#42`,
+`owner/repo#42`, an issue URL) — the same forms `pull.py` takes. Both are
+needed, and for the same reason: a push deletes the local file, so most issues
+in the tracker have no slug on disk to name them by. A slug is resolved through
+the file's `gitea:` field when the file is there, and through the ledger
+(`.remote.json`) when push has already dropped it.
+
+**An `origin: local` issue cannot be closed.** It is not in the tracker, so
+there is nothing to close there, and the run stops naming the id rather than
+quietly editing one field of a local file. Delete it, or push it first.
+
+**Explicit ids only.** No `--milestone`, no `--label`, no "close everything
+that looks done". Which issues are finished is a judgement about content; this
+script only carries it out, one named id at a time. Nothing here deletes an
+issue either — Gitea can, and it is not an operation of this workflow.
+
+The local file is written only after the tracker has confirmed the write:
+
+    1. `tea` ran and exited 0 (a non-2xx exits the run inside `_gitea.api`), and
+    2. the answer is an object carrying the very number that was PATCHed, and
+    3. its `state` is the state we asked for.
+
+Anything else and the file is left exactly as it was — see `confirmed`. An
+issue whose local copy is gone (pushed and dropped) is closed in Gitea and
+nothing is written; the state comes down with the next `pull.py`.
+
+Gitea refuses to close an issue that its own dependency graph still blocks. That
+refusal arrives as a non-2xx and stops the run with the tracker's own words:
+close the blockers first, or unlink them in the web UI.
+
+Login: the operator's pin from .claude/settings.local.json (see /tea:auth).
+"""
+import argparse
+import os
+import re
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path[:0] = [_HERE, os.path.normpath(os.path.join(_HERE, "..", "..", "issue", "scripts"))]
+
+import _gitea  # noqa: E402
+import issue  # noqa: E402
+import issue_index  # noqa: E402
+import map as gmap  # noqa: E402
+
+# What `_gitea.parse_key` accepts, asked as a question instead of an assertion:
+# parse_key exits on anything it cannot read, and here "not a key" is the normal
+# case — it means the argument is a slug. A slug never contains `#`, `/` or `:`,
+# so the two vocabularies cannot collide.
+KEY_RE = re.compile(r'^(#?\d+|[\w.-]+/[\w.-]+#\d+|https?://\S+)$')
+
+
+def looks_like_key(arg):
+    return bool(KEY_RE.match((arg or "").strip()))
+
+
+def ledger_pairs(remote_map, repo=None):
+    """[(repo, number, slug)] from `.remote.json`, filtered to `repo`.
+
+    A `--repo` that was not given means "whatever the ledger holds": resolving
+    the repo's real name costs a request, and a dry run is required to make
+    none. The ambiguity that opens — one number under two repos — is caught at
+    lookup time rather than papered over."""
+    out = []
+    for key, slug in sorted(remote_map.items()):
+        r, n = gmap.parse_remote_key(key)
+        if n:
+            if repo is None or r == repo:
+                out.append((r, n, slug))
+    return out
+
+
+def one(candidates, what, arg):
+    """The single `(repo, value)` in `candidates`, None when empty, or exit.
+
+    Two answers mean the ledger knows this number (or this slug) under more than
+    one repository, and only `--repo` can settle that."""
+    got = sorted(set(candidates))
+    if len(got) > 1:
+        _gitea.die("%r matches %s under more than one repo (%s) — pass "
+                   "--repo owner/repo" % (arg, what, ", ".join(r for r, _v in got)))
+    return got[0] if got else None
+
+
+def resolve(arg, issues, pairs):
+    """(id, number, repo) for one argument. Either of `id` and `repo` is None
+    when nothing this machine holds names it.
+
+    Order, and it is the order of what is most authoritative about this machine:
+    a file on disk, then the ledger, then nothing. A key skips straight to the
+    ledger — its number is already the tracker's answer, and the slug is only
+    wanted so the local copy, if there is one, can be kept honest.
+
+    `repo` travels out with the number because a key may name one
+    (`owner/repo#42`) and a `gitea:` field always does. Sending a foreign key to
+    whatever repo the CWD happens to be in would close somebody else's issue of
+    the same number, so the caller reconciles them before anything goes out."""
+    if looks_like_key(arg):
+        number, repo = _gitea.parse_key(arg)
+        hit = one([(r, s) for r, n, s in pairs
+                   if n == number and (repo is None or r == repo)], "a slug", arg)
+        return (hit[1] if hit else None), number, repo or (hit[0] if hit else None)
+
+    iss = issues.get(arg)
+    if iss is not None:
+        repo, number = gmap.parse_remote_key(iss.extra.get("gitea", ""))
+        if not number:
+            _gitea.die("%s is not in the tracker (origin: %s, no gitea: field) — "
+                       "there is no state there to change; push.py %s first"
+                       % (arg, iss.origin, arg))
+        return arg, number, repo
+
+    hit = one([(r, n) for r, n, s in pairs if s == arg], "a number", arg)
+    if hit:
+        return arg, hit[1], hit[0]  # pushed, and its file went with the push
+    _gitea.die("no issue %r in the store or the ledger — pass a Gitea number "
+               "(42, #42, owner/repo#42, a URL) to close one this machine has "
+               "never seen" % arg)
+
+
+def confirmed(got, number, state):
+    """True when the tracker's answer confirms THIS write, and nothing else.
+
+    The gate in front of the local write, and deliberately boring: an answer
+    counts only when it is an object carrying the very number that was PATCHed
+    (`bool` rejected explicitly — `True` is an `int`) and the state that was
+    asked for. A non-2xx and a `tea` that would not run never reach here at all;
+    `_gitea.api` exits on both, so the file survives those by never being
+    written."""
+    if not isinstance(got, dict):
+        return False
+    n = got.get("number")
+    if isinstance(n, bool) or not isinstance(n, int) or n != number:
+        return False
+    return got.get("state") == state
+
+
+def apply_state(root, iss, state, got):
+    """Write the confirmed state onto the local file; return its path.
+
+    `state:` is the domain's own field, so it is set on the issue and written
+    out by the domain's own writer. The sync-owned freshness fields travel with
+    it: the answer that authorized this write is also the newest thing the
+    tracker has said about the issue, so `synced:` and `remote-updated:` are
+    stamped from it rather than left describing an older read."""
+    iss.state = state
+    iss.extra["synced"] = _gitea.now_iso()
+    if got.get("updated_at"):
+        iss.extra["remote-updated"] = got["updated_at"]
+    return issue.save(root, iss)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Close (or reopen) issues in Gitea")
+    ap.add_argument("ids", nargs="+",
+                    help="local ids, or Gitea keys: 42, #42, owner/repo#42, URL")
+    ap.add_argument("--reopen", action="store_true",
+                    help="set the state back to open instead of closed")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="print what would change; makes no request at all")
+    ap.add_argument("--repo", help="owner/repo (default: auto-detect from CWD git remote)")
+    ap.add_argument("--out", default=issue.ISSUE_ROOT,
+                    help="store root (default: <repo>/tmp/issues)")
+    args = ap.parse_args()
+
+    root = args.out
+    state = "open" if args.reopen else "closed"
+    verb = "reopen" if args.reopen else "close"
+    past = "reopened" if args.reopen else "closed"
+
+    # A store that is not there is not an error here: a number needs no local
+    # file, and closing an issue whose copy was dropped by push is the normal
+    # case. `load_all` reads an absent directory as an empty one.
+    issues = issue.load_all(root)
+    pairs = ledger_pairs(_gitea.load_map(root), args.repo)
+
+    # Every argument is resolved before anything is sent, so a typo in the third
+    # id does not leave the first two closed.
+    targets = []
+    for arg in args.ids:
+        got = resolve(arg, issues, pairs)
+        if got not in targets:
+            targets.append(got)
+
+    # One run, one repo. An explicit --repo is the operator's word and wins;
+    # without one, the repo comes from what the ids themselves said, and two
+    # answers are a question rather than a guess — `repo_base` would otherwise
+    # let `tea` fill the blank from the CWD and close the wrong #42.
+    named = {r for _i, _n, r in targets if r}
+    if not args.repo and len(named) > 1:
+        _gitea.die("all ids must belong to one repo, got: %s" % ", ".join(sorted(named)))
+    repo_arg = args.repo or (sorted(named)[0] if named else None)
+
+    if args.dry_run:
+        for id, number, _repo in targets:
+            iss = issues.get(id)
+            where = ("%s (state: %s)" % (issue.path_of(root, id), iss.state)
+                     if iss is not None else "no local copy")
+            print("would %s  %s  #%d  — %s" % (verb, id or "?", number, where))
+        print("%d issue(s) would be %s; no request was made"
+              % (len(targets), past))
+        return
+
+    login = _gitea.require_login()
+    base = _gitea.repo_base(repo_arg)
+
+    touched = 0
+    for id, number, _repo in targets:
+        got = _gitea.api(login, "%s/issues/%d" % (base, number), "PATCH",
+                         {"state": state}, payload_name="state-%d" % number)
+        # The gate. Above it nothing local has been written; below it the file
+        # is about to say something the tracker had better agree with.
+        if not confirmed(got, number, state):
+            _gitea.die("#%d: %s failed — the tracker's answer does not confirm the "
+                       "write (%.200r). Nothing local was changed."
+                       % (number, verb, got))
+
+        print("%s  %s  #%d  %s" % (past, id or "?", number,
+                                   got.get("html_url", "")))
+
+        iss = issues.get(id)
+        if iss is None:
+            print("    no local copy — pull.py %d to get one" % number)
+            continue
+        print("    state: %s  %s" % (state, apply_state(root, iss, state, got)))
+        touched += 1
+
+    if touched:
+        path, n = issue_index.build(root)
+        print("index: %s — %d issue(s)" % (path, n))
+
+
+if __name__ == "__main__":
+    main()

skills/sync/scripts/comment.py

@@ -73,13 +73,11 @@ def main():
 
     if args.edit:
         got = _gitea.api(login, "%s/issues/comments/%d" % (base, args.edit), "PATCH",
-                         {"body": body}, payload_name="comment-%d" % args.edit,
-                         out_root=root)
+                         {"body": body}, payload_name="comment-%d" % args.edit)
         verb = "edited"
     else:
         got = _gitea.api(login, "%s/issues/%d/comments" % (base, number), "POST",
-                         {"body": body}, payload_name="comment-%s" % args.id,
-                         out_root=root)
+                         {"body": body}, payload_name="comment-%s" % args.id)
         verb = "posted"
     if not isinstance(got, dict) or "id" not in got:
         _gitea.die("%s failed, unexpected response" % verb)

skills/sync/scripts/labels.py

@@ -32,6 +32,11 @@ created by push as they come up, and deleting or renaming anything at all.
 Only repository labels are read; an organization's own labels sit behind a
 different endpoint and are neither read nor written.
 
+The issue store is out of scope too, and not incidentally. A label belongs to
+the repository, not to any issue, so this command neither reads tmp/issues/ nor
+creates it — the taxonomy it paints comes from the domain MODULE, and the
+request bodies it sends go to the transport's own tmp/payload/.
+
 Login: the operator's pin from .claude/settings.local.json (see /tea:auth).
 """
 import argparse
@@ -185,8 +190,7 @@ def main():
                 continue
             payload = dict(spec, name=name)
             new = _gitea.api(login, "%s/labels" % base, "POST", payload,
-                             payload_name="label-%s" % name.replace("/", "-"),
-                             out_root=issue.ISSUE_ROOT)
+                             payload_name="label-%s" % name.replace("/", "-"))
             if not new or "id" not in new:
                 _gitea.die("could not create label %r" % name)
             print("created  %-20s id %-5s %s%s" % (name, new["id"], spec["color"], mark))
@@ -211,8 +215,7 @@ def main():
         for field, _is, _want in drift:
             patch[field] = spec[field]
         _gitea.api(login, "%s/labels/%s" % (base, got.get("id")), "PATCH", patch,
-                   payload_name="label-%s" % name.replace("/", "-"),
-                   out_root=issue.ISSUE_ROOT)
+                   payload_name="label-%s" % name.replace("/", "-"))
         fixed += 1
         print("fixed    %-20s id %-5s %s" % (name, got.get("id"), shown))
 

skills/sync/scripts/pull.py

@@ -28,11 +28,31 @@ not exposed (404 on Gitea 1.26) — use milestones or labels, or the web UI.
 
 A closed issue is not a unit of work, so filter mode enumerates it but leaves
 it out of the store: `--state all` still shows the whole picture, and only
-`--state closed` writes one. The limit is on the write, not on the selection —
-an issue already on disk is refreshed either way, so the local copy learns it
-was closed instead of staying open forever, and the count of the ones left out
-goes to stderr. Key mode is exempt: an address is not a bulk read, and
-`pull.py 1` fetches a closed issue as it always did.
+`--state closed` writes one. An issue already on disk is refreshed either way,
+so the local copy learns it was closed instead of staying open forever, and the
+count of the ones left out goes to stderr. Key mode is exempt: an address is not
+a bulk read, and `pull.py 1` fetches a closed issue as it always did.
+
+**`--limit` is on the write, not on the selection.** It counts the issues this
+run puts in the store — written, or left in place by `--cached` — and never the
+closed ones it enumerated and threw away. `--limit 20` over a milestone whose
+first 30 issues are closed still writes 20, if 20 open ones are there to write:
+pages keep coming until the budget is full. Two boundaries keep that honest:
+
+- Pages stop the moment the budget is full. Never one page more.
+- A filtered read may scan at most `_gitea.PAGE_SLACK` times the pages the limit
+  would need if nothing were dropped. A filter that matches almost only closed
+  issues therefore ends in a warning and a short answer, not in a walk of the
+  whole tracker. Narrow the filter, or raise `--limit`, which raises the budget
+  with it.
+- Dependencies are outside the count: a blocker is followed because a stored
+  issue named it, not because the filter selected it. `--limit 20` can
+  therefore leave more than 20 files behind — the budget counts the selection's
+  writes, and the graph is not part of the selection.
+
+`remote.py` is the deliberate exception, and it is not the same flag twice: it
+writes nothing at all, so there is no write to bound and its `--limit` means
+what it says — how many lines to print.
 
 Comments ride along by default, in both modes and for every issue written:
 the thread lands in tmp/issues/<id>.comments.md, beside the issue. It costs
@@ -42,8 +62,39 @@ from an earlier pull is deleted. An absent file therefore means "no comments",
 never "not asked for". The thread is pull-only: editing it changes nothing in
 Gitea (post with comment.py).
 
+**Dependencies come with every pull.** A pull answers with the whole unit of
+work — the issue and what blocks it — so `depends:` is filled from Gitea's
+native dependency graph and every blocker is pulled too, recursively, down to
+`--depth` (default 3). That graph is the only source there is: `map.from_api`
+writes slugs into the `## Depends on` prose and never `#N`, so an edge cannot be
+recovered from the body. `--no-deps` turns off both halves — no `depends:`, no
+recursion, and no request spent on either. `--deps` is still accepted and now
+does nothing; it names what already happens.
+
+What it costs, stated rather than hidden:
+
+- **One request per issue that lands in the store** — `GET …/issues/{n}/dependencies`,
+  fetched once and used twice, since the same links both fill `depends:` and
+  tell the walk where to go next. A closed issue that filter mode drops costs
+  nothing: nothing was stored, so there is no unit of work to complete.
+- **One request per blocker the selection did not already carry** — a `GET` for
+  the issue itself, then its own links, and so on until `--depth`.
+- So `--milestone X` over 50 open issues is one list request + 50 link requests
+  + one pair for every blocker outside the milestone, where it used to be one
+  request flat. `--no-deps` is the way back to one.
+
+**In filter mode a blocker the filter did not select still lands in the store,
+and that is deliberate.** `--milestone X` can leave an issue from milestone Y on
+disk and `--label` an unlabelled one: a blocker is followed because a stored
+issue names it, not because it matched. The one blocker that does not land is a
+closed one — closed is not a unit of work, filter mode drops it the way it drops
+any other closed issue, and the `depends:` edge to it goes with it, so nothing
+points at a file that is not there. Key mode has no such rule and stores it.
+
 Other flags:
-    --deps [--depth N]   follow dependencies and pull them too
+    --no-deps            do not fill depends:, do not follow blockers
+    --deps               accepted, does nothing: it is the default now
+    --depth N            how deep to follow blockers (default 3)
     --cached             skip issues already on disk (body AND comments)
     --repo owner/repo    default: auto-detect from the CWD git remote
 
@@ -52,7 +103,9 @@ have not pushed are lost — with exactly one exception, checkbox state. A `[x]`
 on either side wins for any item whose text matches, because a tick is monotone
 and unioning the two sides is not conflict resolution (gmap.merge_checkbox_state
 has the rule and its price). `--cached` skips an issue before any of that: it is
-not read and not merged. Draw the graph afterwards with the domain's own
+not read and not merged — it still costs its one link request, because a cached
+issue's blockers can be missing from disk even when it is not (`--cached
+--no-deps` is the free one). Draw the graph afterwards with the domain's own
 issue_tree.py — it needs no network.
 
 Login: the operator's pin from .claude/settings.local.json (see /tea:auth).
@@ -98,6 +151,23 @@ def id_for(payload, store_ids, remote_map, repo, root):
                            taken=store_ids)
 
 
+def lands_in_store(payload, drop_closed, store_ids, remote_map, repo, root):
+    """Would this payload leave a file in the store? The `--limit` predicate.
+
+    It has to be the same test the walk below applies, or the budget is spent on
+    issues that never land — which is the bug this exists to prevent. So: a
+    closed issue counts only when the store already has it (it is refreshed, and
+    that is a write); anything else counts, including one `--cached` will skip,
+    because a skipped issue is still an issue the store holds when the run ends.
+
+    Cheap in the common case: only a closed payload costs an `id_for`, and that
+    is a lookup plus, at worst, a stat."""
+    if not (drop_closed and payload.get("state") == "closed"):
+        return True
+    id = id_for(payload, store_ids, remote_map, repo, root)
+    return os.path.isfile(issue.path_of(root, id))
+
+
 def comments_path(root, id):
     """Where an issue's comment thread lives — beside it, under the same slug.
     Named in `_gitea` because push.py has to delete the same file."""
@@ -131,8 +201,18 @@ def main():
     ap.add_argument("-q", "--query", help="search text in title/body")
     ap.add_argument("--state", default="open", choices=["open", "closed", "all"],
                     help="filter mode only (default: open)")
-    ap.add_argument("--limit", type=int, default=100, help="filter mode cap (default: 100)")
-    ap.add_argument("--deps", action="store_true", help="follow dependencies and pull them")
+    ap.add_argument("--limit", type=int, default=100,
+                    help="filter mode: how many issues to STORE, not to enumerate"
+                         " (default: 100)")
+    # Dependencies are the default: a pull answers with the unit of work, not
+    # one row of it. `--deps` stays accepted so the calls and command tables
+    # written against the old default keep working — it now sets what is
+    # already set.
+    ap.add_argument("--no-deps", dest="deps", action="store_false",
+                    help="do not fill depends: and do not follow blockers")
+    ap.add_argument("--deps", dest="deps", action="store_true",
+                    help="accepted, does nothing: dependencies are followed by default")
+    ap.set_defaults(deps=True)
     ap.add_argument("--depth", type=int, default=3, help="max dependency depth (default: 3)")
     ap.add_argument("--cached", action="store_true",
                     help="skip issues already on disk instead of refetching")
@@ -180,9 +260,14 @@ def main():
 
     # ---- seeds -----------------------------------------------------------
     if filtered:
+        # The limit bounds the write, so the transport is told what a write is
+        # and counts those; the closed ones it enumerated on the way come back
+        # in the list anyway, to be reported and dropped below.
         payloads, ms_title = _gitea.list_issues(
             login, base, state=args.state, labels=args.label, query=args.query,
-            milestone=args.milestone, limit=args.limit)
+            milestone=args.milestone, limit=args.limit,
+            keep=lambda p: lands_in_store(p, drop_closed, store_ids, remote_map,
+                                          repo, root))
         if not payloads:
             _gitea.die("no issues match that filter")
         what = []
@@ -208,35 +293,42 @@ def main():
         stored = os.path.isfile(issue.path_of(root, id))
 
         # Closed and not already ours: nothing is written and nothing is asked
-        # of the server for it, not even its comments. The slug stays unclaimed
-        # too, so no other issue ends up pointing `depends:` at a missing file.
+        # of the server for it — not its comments, not its links, and its own
+        # blockers are not followed. The slug stays unclaimed too, so no other
+        # issue ends up pointing `depends:` at a missing file.
         if drop_closed and payload.get("state") == "closed" and not stored:
             dropped.append(number)
+            continue  # not stored: no unit of work here, so no links are fetched
+
+        store_ids.add(id)
+        number_of_id[number] = id
+
+        # The native links, fetched ONCE for the two things they are for:
+        # filling this issue's `depends:` and telling the walk where to go next.
+        # One request per issue that lands in the store, and only one — the cost
+        # the docstring quotes is this line.
+        deps = _gitea.native_deps(login, base, number) if args.deps else []
+
+        if args.cached and stored:
+            skipped.append(id)  # body and thread unread; only the links cost
         else:
-            store_ids.add(id)
-            number_of_id[number] = id
-            if args.cached and stored:
-                skipped.append(id)  # untouched, unread, and not one request spent
-            else:
-                extra = _gitea.native_deps(login, base, number) if args.deps else []
-                # The copy already on disk, as it was when this run started. It
-                # contributes its ticked checkboxes and nothing else; None when
-                # the store has never seen this issue.
-                prev = issues.get(id)
-                iss, unresolved = gmap.from_api(payload, id, repo,
-                                                id_for_number=number_of_id,
-                                                extra_numbers=extra,
-                                                synced=_gitea.now_iso(),
-                                                local_body=prev.body if prev else None)
-                issue.save(root, iss)
-                sync_comments(login, base, root, id, number, payload.get("comments") or 0)
-                remote_map[gmap.remote_key(repo, number)] = id
-                written.append(id)
-                pending.append((id, unresolved))
+            # The copy already on disk, as it was when this run started. It
+            # contributes its ticked checkboxes and nothing else; None when
+            # the store has never seen this issue.
+            prev = issues.get(id)
+            iss, unresolved = gmap.from_api(payload, id, repo,
+                                            id_for_number=number_of_id,
+                                            extra_numbers=deps,
+                                            synced=_gitea.now_iso(),
+                                            local_body=prev.body if prev else None)
+            issue.save(root, iss)
+            sync_comments(login, base, root, id, number, payload.get("comments") or 0)
+            remote_map[gmap.remote_key(repo, number)] = id
+            written.append(id)
+            pending.append((id, unresolved))
 
         if args.deps and depth < args.depth:
-            child_numbers = (gmap.numbers_in_body(payload.get("body") or "")
-                             + _gitea.native_deps(login, base, number))
+            child_numbers = gmap.numbers_in_body(payload.get("body") or "") + deps
             for n in child_numbers:
                 if n in seen_numbers:
                     continue
@@ -265,8 +357,10 @@ def main():
 
     # Compact output — the only thing that lands in the model's context. The
     # thread rides on the issue's own line; no file means no comments.
+    graph = False
     for id in sorted(set(written) | set(skipped)):
         iss = issue.load(root, id)
+        graph = graph or bool(iss.depends)
         note = "  (cached)" if id in skipped else ""
         cpath = comments_path(root, id)
         if os.path.isfile(cpath):
@@ -275,7 +369,9 @@ def main():
             id, ", ".join(iss.labels) or "no labels", iss.title, iss.state,
             issue.path_of(root, id), note))
     print("index: %s" % index_path)
-    if args.deps:
+    # Now that dependencies are the default, the hint is worth printing when
+    # there is something to draw, not on every run that could have drawn it.
+    if graph:
         print("graph: run issue_tree.py (offline) to draw it")
 
 

skills/sync/scripts/push.py

@@ -44,7 +44,7 @@ way, so nothing is lost, but the tracker shows no edge for it.
 
 The graph goes up with them. Once an issue has its number, every `depends:`
 entry that also has one becomes a **native Gitea link** — the same
-`/dependencies` that `pull.py --deps` reads back, so the tracker shows the
+`/dependencies` that every `pull.py` reads back, so the tracker shows the
 blocking panel and refuses to close a blocked issue first. Topological order
 means the blocker already has its number by then; no second pass is needed.
 `--update` links whatever appeared in `depends:` since the last push. A link
@@ -334,12 +334,12 @@ def main():
         if sent_number:
             payload = gmap.to_payload(iss, label_ids, ms_id, include_state=True)
             got = _gitea.api(login, "%s/issues/%d" % (base, sent_number), "PATCH",
-                             payload, payload_name="issue-%s" % id, out_root=root)
+                             payload, payload_name="issue-%s" % id)
             verb = "updated"
         else:
             payload = gmap.to_payload(iss, label_ids, ms_id)
             got = _gitea.api(login, "%s/issues" % base, "POST", payload,
-                             payload_name="issue-%s" % id, out_root=root)
+                             payload_name="issue-%s" % id)
             verb = "created"
         # The gate. Below this line the local file is going to be deleted, so
         # anything short of a confirmed write has to stop the run here.
@@ -364,7 +364,7 @@ def main():
         if missing:
             _gitea.api(login, "%s/issues/%d/labels" % (base, number), "PUT",
                        {"labels": [label_ids[l] for l in iss.labels if l in label_ids]},
-                       payload_name="labels-%s" % id, out_root=root)
+                       payload_name="labels-%s" % id)
             _gitea.warn("%s: labels re-applied via PUT (%s)" % (id, ", ".join(missing)))
 
         # The in-memory issue is stamped even though its file is going: the rest
@@ -392,7 +392,7 @@ def main():
             for slug, (drepo, dnum) in wanted_links:
                 if not dnum or (drepo, dnum) in have:
                     continue
-                if _gitea.add_dependency(login, base, number, drepo, dnum, root):
+                if _gitea.add_dependency(login, base, number, drepo, dnum):
                     print("    depends on  %s#%d  (%s)" % (drepo, dnum, slug))
                 else:
                     _gitea.warn("%s: could not link #%d -> %s#%d (%s) — link it by "

skills/sync/scripts/remote.py

@@ -16,6 +16,11 @@ Usage:
     remote.py [--state open|closed|all] [--label L]… [-q TEXT]
               [--milestone M] [--limit N] [--repo owner/repo]
 
+`--limit` here caps the LISTING: N lines out, closed ones among them. That is
+not what the same flag means to `pull.py`, and the difference is not an
+oversight — pull.py bounds what it writes, and this command writes nothing, so
+there is nothing else for a limit to bound. Enumeration is the whole job.
+
 Login: the operator's pin from .claude/settings.local.json (see /tea:auth).
 """
 import argparse

skills/wiki/SKILL.md

@@ -11,7 +11,8 @@ ordering, paths, the index — belongs to `/tea:page` and is imported from there
 never redefined here.
 
 Transport is `tea api` through `skills/sync/scripts/_gitea.py`: the same login
-pin, the same pagination, the same payload files. There is no second transport.
+pin, the same pagination, the same payload files in the same `tmp/payload/`.
+There is no second transport.
 
 ## The wiki is flat, and that is the whole design
 

skills/wiki/scripts/wiki_push.py

@@ -115,13 +115,12 @@ def main():
         if verb == "create":
             payload = wikimap.new_payload(title, text, a.message)
             got = _gitea.api(login, "%s/wiki/new" % base, method="POST",
-                             payload=payload, payload_name="wiki-new",
-                             out_root=space_dir)
+                             payload=payload, payload_name="wiki-new")
         else:
             payload = wikimap.edit_payload(title, text, a.message)
             got = _gitea.api(login, wikimap.page_endpoint(base, e["sub_url"]),
                              method="PATCH", payload=payload,
-                             payload_name="wiki-edit", out_root=space_dir)
+                             payload_name="wiki-edit")
 
         if not isinstance(got, dict) or not got.get("sub_url"):
             _gitea.warn("%s: no page returned; the manifest is unchanged for it"