margin 0.2.1__py3-none-any.whl

margin/batch.py

@@ -0,0 +1,41 @@
+"""When to tell the agent about comments: a settle window, so a burst becomes one message.
+
+A route (one repo's chat) has a batch open from its first undelivered comment. The batch is ready
+when the person has been quiet for `quiet` seconds, or `cap` seconds after its first comment so a
+long reading session still gets answers, or at once when a comment mentions the agent.
+
+Times are this machine's receive times (seconds since the epoch), never the server's timestamps,
+so a clock or timezone difference between the two cannot hold a batch back or release it early.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+
+
+def ready(rows, now: float, quiet: float, cap: float) -> dict[str, list]:
+    by_route: dict[str, list] = defaultdict(list)
+    for r in rows:
+        by_route[r["route"]].append(r)
+    out = {}
+    for route, rs in by_route.items():
+        first = min(r["received_at"] for r in rs)
+        last = max(r["received_at"] for r in rs)
+        if any(r["mentions_agent"] for r in rs) or now - last >= quiet or now - first >= cap:
+            out[route] = sorted(rs, key=lambda r: r["received_at"])
+    return out
+
+
+def due_in(rows, now: float, quiet: float, cap: float) -> float | None:
+    """Seconds until the next batch becomes ready, for a status line. None when nothing waits."""
+    if not rows:
+        return None
+    best = None
+    by_route: dict[str, list] = defaultdict(list)
+    for r in rows:
+        by_route[r["route"]].append(r)
+    for rs in by_route.values():
+        first = min(r["received_at"] for r in rs)
+        last = max(r["received_at"] for r in rs)
+        t = max(0.0, min(last + quiet, first + cap) - now)
+        best = t if best is None else min(best, t)
+    return best

margin/claude.py

@@ -0,0 +1,89 @@
+"""`margin setup-claude`: wire margin and Outline into Claude Code, idempotently.
+
+Three things, each safe to run again:
+
+1. the margin skill, linked into ~/.claude/skills/margin from this package, so it updates with it;
+2. Outline's own MCP server registered in ~/.claude.json, with the agent's key supplied at connect
+   time by a small headers script that runs `api_key_command`, so the key is never written into
+   a config file;
+3. Outline's destructive MCP tools denied in ~/.claude/settings.json. An agent that deletes or
+   moves a document, or changes a collection, would break the folder structure margin mirrors.
+
+Both JSON files are backed up once per run before they are rewritten, atomically.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+from .config import Config
+
+DENY = ["delete_document", "delete_collection", "update_collection", "create_collection",
+        "move_document"]
+
+
+def _rewrite(path: Path, change) -> bool:
+    data = json.loads(path.read_text()) if path.exists() else {}
+    before = json.dumps(data, sort_keys=True)
+    change(data)
+    if json.dumps(data, sort_keys=True) == before:
+        return False
+    if path.exists():
+        shutil.copy2(path, path.with_name(path.name + f".bak-margin-{time.strftime('%Y%m%d%H%M%S')}"))
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent))
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, path)
+    return True
+
+
+def setup(cfg: Config, home: Path | None = None, name: str = "outline") -> list[str]:
+    home = home or Path.home()
+    done = []
+
+    # 1. the skill
+    skill_src = Path(__file__).parent / "skills" / "margin"
+    skills = home / ".claude" / "skills"
+    skills.mkdir(parents=True, exist_ok=True)
+    link = skills / "margin"
+    if link.is_symlink() or not link.exists():
+        if not (link.is_symlink() and Path(os.readlink(link)) == skill_src):
+            if link.is_symlink():
+                link.unlink()
+            link.symlink_to(skill_src)
+            done.append(f"skill linked: {link} -> {skill_src}")
+    else:
+        done.append(f"skill left alone: {link} exists and is not a link")
+
+    # 2. the MCP server and its headers script
+    helper = home / ".config" / "margin" / "outline-mcp-headers.sh"
+    helper.parent.mkdir(parents=True, exist_ok=True)
+    body = ("#!/bin/sh\n# written by margin setup-claude: the agent's Outline key, read at connect time\n"
+            f"k=$({shlex.join(cfg.api_key_command)}) || exit 1\n"
+            "printf '{\"Authorization\": \"Bearer %s\"}\\n' \"$k\"\n")
+    if not helper.exists() or helper.read_text() != body:
+        helper.write_text(body)
+        done.append(f"headers script written: {helper}")
+    helper.chmod(0o700)
+    url = cfg.mcp_url or cfg.url.rstrip("/") + "/mcp"
+
+    def add_server(d):
+        d.setdefault("mcpServers", {})[name] = {"type": "http", "url": url,
+                                               "headersHelper": str(helper)}
+    if _rewrite(home / ".claude.json", add_server):
+        done.append(f"MCP server '{name}' registered at {url}")
+
+    # 3. deny the destructive tools
+    def deny(d):
+        lst = d.setdefault("permissions", {}).setdefault("deny", [])
+        for t in DENY:
+            if f"mcp__{name}__{t}" not in lst:
+                lst.append(f"mcp__{name}__{t}")
+    if _rewrite(home / ".claude" / "settings.json", deny):
+        done.append("destructive Outline tools denied: " + ", ".join(DENY))
+    return done or ["already set up"]

margin/cli.py

@@ -0,0 +1,294 @@
+"""margin: publish repo markdown to Outline and bring comments back to an agent.
+
+    margin sync [REPO...] [--full]     publish changed files (all repos when none named)
+    margin serve                       webhook receiver + catch-up poll + batching + periodic sync
+    margin webhook                     create Outline's webhook subscription if it is missing
+    margin status                      documents that need attention, and comments waiting
+    margin reply COMMENT_ID TEXT       answer in the comment's thread, as the configured user
+    margin resolve COMMENT_ID          mark the thread resolved
+    margin thread COMMENT_ID           print a whole thread with its quoted text
+    margin link FILE...                publish these files now and print a Markdown link to each
+    margin setup-claude                install the skill, Outline's MCP and its tool denials
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import json
+import sys
+import time
+
+from . import batch
+from .config import DEFAULT_PATH, load, locate
+from .inbox import EVENTS, Inbox, serve
+from .outline import Outline, comment_text, pin_host
+from .store import Store
+from .sync import Syncer
+
+
+def connect(cfg):
+    if cfg.pin_ip_command:
+        from urllib.parse import urlparse
+        pin_host(urlparse(cfg.url).hostname, cfg.run(cfg.pin_ip_command).split()[0])
+    return Outline(cfg.url, cfg.api_key())
+
+
+def ensure_webhook(cfg, o: Outline) -> str:
+    """Webhook subscriptions need an admin. The agent's own key is a member's, on purpose, so the
+    admin key is used for this one call only and never kept on the client."""
+    if not (cfg.webhook_url and cfg.secret_command):
+        return "no webhook configured; the catch-up poll is the only path"
+    if not cfg.admin_key_command:
+        return "no admin_key_command; create the webhook once as an admin (margin webhook)"
+    admin = Outline(cfg.url, cfg.run(cfg.admin_key_command))
+    w = admin.ensure_webhook("margin", cfg.webhook_url, cfg.secret(), EVENTS)
+    return f"webhook {w['id']} -> {w['url']} ({', '.join(w.get('events') or [])})"
+
+
+def thread_of(o: Outline, comment_id: str) -> tuple[dict, list[dict]]:
+    c = o.comment(comment_id)
+    root = o.comment(c["parentCommentId"]) if c.get("parentCommentId") else c
+    rows = [x for x in o.comments(document_id=root["documentId"])
+            if x["id"] == root["id"] or x.get("parentCommentId") == root["id"]]
+    return root, sorted(rows, key=lambda x: x["createdAt"])
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="margin", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--config", default=str(DEFAULT_PATH))
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("sync")
+    p.add_argument("repos", nargs="*")
+    p.add_argument("--full", action="store_true")
+    sub.add_parser("serve")
+    sub.add_parser("webhook")
+    sub.add_parser("status")
+    p = sub.add_parser("reply")
+    p.add_argument("comment_id")
+    p.add_argument("text")
+    p = sub.add_parser("resolve")
+    p.add_argument("comment_id")
+    p = sub.add_parser("thread")
+    p.add_argument("comment_id")
+    p = sub.add_parser("link")
+    p.add_argument("files", nargs="+")
+    p = sub.add_parser("accept-file", help="let the file win a conflict no person made")
+    p.add_argument("files", nargs="+")
+    p = sub.add_parser("accept-merged",
+                       help="publish a file that now carries a person's Outline edit")
+    p.add_argument("files", nargs="+")
+    p.add_argument("--undo", action="append", default=[],
+                   help="text from a part of their edit the person agreed to undo (repeatable)")
+    sub.add_parser("setup-claude")
+    sub.add_parser("anchors", help="record where each older comment's passage sits in its document")
+    p = sub.add_parser("pinch-check", help="pinch a fold page on an Android phone over adb and judge each pinch")
+    p.add_argument("page", help="the fold page (margin fold --html)")
+    p.add_argument("--serial", required=True, help="the phone, as adb names it")
+    p.add_argument("--package", default="com.brave.browser", help="the phone's Chromium browser")
+    p.add_argument("--out", help="the folder for the table, the readings and the recording")
+    p.add_argument("--wait-unlock", type=float, default=0.0,
+                   help="seconds to wait for the phone to be awake and unlocked (never unlocked for you)")
+    p = sub.add_parser("fold", help="fold a markdown file into five levels of detail, each checked")
+    p.add_argument("file")
+    p.add_argument("--out", help="write the fold as JSON here")
+    p.add_argument("--html", help="write a page to read the fold here")
+    p.add_argument("--model", default="sonnet")
+    p.add_argument("--judge-model", default="opus")
+    a = ap.parse_args(argv)
+
+    if a.cmd == "pinch-check":
+        from pathlib import Path as P
+        from .pinch_check import run as pinch_run
+        return pinch_run(P(a.page).expanduser().resolve(), a.serial, package=a.package,
+                         out=P(a.out).expanduser() if a.out else None, wait_unlock=a.wait_unlock)
+
+    if a.cmd == "fold":
+        from functools import partial
+        from pathlib import Path as P
+        from .fold import ask_claude, ask_judge, fold_file
+        cache = P(os.environ.get("MARGIN_FOLD_CACHE", "~/.cache/margin/folds")).expanduser()
+        f = fold_file(P(a.file), out=P(a.out) if a.out else None, html_out=P(a.html) if a.html else None,
+                      cache=cache, ask=partial(ask_claude, model=a.model),
+                      judge=partial(ask_judge, model=a.judge_model))
+        c = f["counts"]
+        print(f"folded {a.file}: {c['units']} paragraphs, {c['claude']} by Claude, "
+              f"{c['author']} kept in the author's words, {c['calls']} calls")
+        for s in f["sections"]:
+            for u in s["units"]:
+                if u["source"] == "author":
+                    print(f"  author's words: {u['id']}: {'; '.join(u['refused'])}")
+            if s["section"]["source"] == "author":
+                print(f"  section in the author's words: {s['id']}: {'; '.join(s['section']['refused'])}")
+        return 0
+
+    from pathlib import Path
+    cfg = load(Path(a.config).expanduser())
+    if a.cmd == "setup-claude":
+        from .claude import setup
+        for line in setup(cfg):
+            print(line)
+        return 0
+    o = connect(cfg)
+    store = Store(cfg.state)
+
+    def sync_all(names=(), full=False, quiet=True):
+        out = []
+        for repo in cfg.repos:
+            if names and repo.name not in names:
+                continue
+            for r in Syncer(o, store, repo, full=full).run():
+                if not quiet or r.action != "unchanged":
+                    out.append((repo.name, r))
+        return out
+
+    if a.cmd == "sync":
+        unknown = set(a.repos) - {r.name for r in cfg.repos}
+        if unknown:
+            print(f"unknown repo(s): {', '.join(sorted(unknown))}", file=sys.stderr)
+            return 2
+        res = sync_all(a.repos, a.full)
+        for repo, r in res:
+            print(f"{r.action:18} {repo}/{r.path}" + (f"  ({r.detail})" if r.detail else ""))
+        if not res:
+            print("nothing changed")
+        return 1 if any(r.action in ("error", "cannot-patch") for _, r in res) else 0
+
+    if a.cmd == "serve":
+        # Outline may still be starting (a 502 from its proxy): wait for it instead of exiting
+        o.wait_ready(log=lambda m: print(m, file=sys.stderr, flush=True))
+        inbox = Inbox(cfg, o, store)
+        try:
+            print(ensure_webhook(cfg, o), flush=True)
+        except Exception as e:                   # the poll still delivers without the webhook
+            print(f"webhook not ensured: {e}", file=sys.stderr, flush=True)
+
+        def sync_pass():
+            for repo, r in sync_all():
+                print(f"sync: {r.action} {repo}/{r.path}" + (f"  ({r.detail})" if r.detail else ""),
+                      flush=True)
+                # a changed text moves its passages, and a rewritten one loses its mark
+                row = store.doc(repo, r.path) if r.action in ("patched", "outline-edited") else None
+                if row:
+                    inbox.place(row["doc_id"])
+
+        serve(inbox, sync_pass)
+        return 0
+
+    if a.cmd == "webhook":
+        print(ensure_webhook(cfg, o))
+        return 0
+
+    if a.cmd == "status":
+        bad = [d for d in store.docs() if d["status"] != "ok"]
+        for d in bad:
+            print(f"{d['status']:18} {d['repo']}/{d['path']}  {d['detail'] or ''}")
+        pend = store.pending()
+        wait = batch.due_in(pend, time.time(), cfg.quiet_seconds, cfg.cap_seconds)
+        print(f"{len(store.docs())} documents, {len(bad)} need attention, {len(pend)} comment(s) "
+              "waiting" + (f", next batch in {int(wait)} s" if wait is not None else ""))
+        return 0
+
+    if a.cmd == "anchors":
+        inbox = Inbox(cfg, o, store)
+        done = gone = 0
+        for doc_id in dict.fromkeys(r["document_id"] for r in store.without_anchor_before()):
+            p, g = inbox.place(doc_id)
+            done, gone = done + p, gone + g
+        print(f"{done} passage(s) placed, {gone} with no mark left in their document")
+        return 0
+
+    if a.cmd == "reply":
+        c = o.comment(a.comment_id)
+        root = c.get("parentCommentId") or c["id"]
+        r = o.reply(c["documentId"], root, a.text)
+        print(f"replied in thread {root} as {o.me()['name']}: {r['id']}")
+        return 0
+
+    if a.cmd == "resolve":
+        c = o.comment(a.comment_id)
+        o.resolve(c.get("parentCommentId") or c["id"])
+        print("resolved")
+        return 0
+
+    if a.cmd == "link":
+        from .outline import doc_url
+        by_repo: dict = {}
+        bad = 0
+        for f in a.files:
+            hit = locate(cfg, Path(f))
+            if not hit:
+                print(f"not published: {f} is in no configured repo (nor in a git worktree of "
+                      "one). Put it in a repo margin publishes, or add its repo to the config.",
+                      file=sys.stderr)
+                bad = 1
+                continue
+            by_repo.setdefault((hit[0].name, hit[2]), (hit[0], []))[1].append(hit[1])
+        author = cfg.author()            # the comments on what you link come back to you
+        for (name, root), (repo, rels) in by_repo.items():
+            got = {rel: (d, st, det)
+                   for rel, d, st, det in Syncer(o, store, repo).publish_status(rels, root)}
+            for rel, (d, _, _) in got.items():
+                if d and author:
+                    store.put(f"author:{d['id']}", author)
+            for rel in rels:
+                d, status, detail = got.get(rel, (None, "", ""))
+                if d and status == "ok":
+                    print(f"[{d['title']}]({doc_url(cfg.url, d)})")
+                elif d:
+                    # The document exists but does not say what the file says. A link printed here
+                    # read as "published" and a chat reported a section that never reached Outline.
+                    # ⭐ which kind it is, so a chat neither stops to ask about an edit nobody made
+                    # nor forces its file over one a person did make (2026-10-16)
+                    why = (" Nobody edited it: margin could not patch it into the file's text. "
+                           "`margin accept-file` publishes the file when only margin has edited it."
+                           if status in ("cannot-patch", "drift") else
+                           " Someone may have edited it in Outline: `margin accept-file` publishes the "
+                           "file only if nobody did, and otherwise names who did.")
+                    print(f"not published: {name}/{rel} is {status}"
+                          + (f" ({detail})" if detail else "")
+                          + f". The document still has the older text: [{d['title']}]"
+                          f"({doc_url(cfg.url, d)}).{why}", file=sys.stderr)
+                    bad = 1
+                else:
+                    print(f"not published: {name}/{rel} is excluded by the repo's include or "
+                          "exclude patterns, or is not markdown", file=sys.stderr)
+                    bad = 1
+        return bad
+
+    if a.cmd in ("accept-file", "accept-merged"):
+        from .outline import doc_url
+        bad = 0
+        for f in a.files:
+            hit = locate(cfg, Path(f))
+            if not hit:
+                print(f"refused: {f} is in no configured repo", file=sys.stderr)
+                bad = 1
+                continue
+            s = Syncer(o, store, hit[0])
+            if a.cmd == "accept-file":
+                r = s.accept_file(hit[1], hit[2])
+            else:
+                r = s.accept_merged(hit[1], hit[2], tuple(a.undo))
+            row = store.doc(hit[0].name, r.path)
+            if r.action in ("patched", "unchanged") and row and row["status"] == "ok":
+                d = o.document(row["doc_id"])
+                print(f"accepted the file: [{d['title']}]({doc_url(cfg.url, d)})")
+            else:
+                print(f"refused: {hit[0].name}/{hit[1]} ({r.action}"
+                      + (f": {r.detail}" if r.detail else "") + ")", file=sys.stderr)
+                bad = 1
+        return bad
+
+    if a.cmd == "thread":
+        root, rows = thread_of(o, a.comment_id)
+        if root.get("anchorText"):
+            print(f'on "{root["anchorText"]}"')
+        for x in rows:
+            print(f"[{x['id']}] {x['createdBy']['name']}: {comment_text(x.get('data'))}")
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

margin/config.py

@@ -0,0 +1,188 @@
+"""margin's configuration: one TOML file, by default ~/.config/margin/config.toml.
+
+    [outline]
+    url = "https://docs.example.com"
+    api_key_command = ["security", "find-generic-password", "-s", "outline-api-key", "-w"]
+    pin_ip_command = ["tailscale", "ip", "-4"]      # optional: resolve the url's host to this IP
+    admin_key_command = [...]   # optional: an admin's key, used ONLY to create the webhook
+    mcp_url = "http://127.0.0.1:3100/mcp"           # optional: Outline's MCP, default <url>/mcp
+
+    [intake]
+    listen = "127.0.0.1:8771"
+    webhook_url = "http://host.docker.internal:8771/outline"   # what Outline posts to
+    secret_command = ["security", "find-generic-password", "-s", "margin-webhook-secret", "-w"]
+    poll_seconds = 600
+
+    [batch]
+    quiet_seconds = 180
+    cap_seconds = 900
+
+    [notify]
+    command = ["my-notifier", "{route}"]     # gets the batch as JSON on stdin. {text} is the
+    cwd = "~/somewhere"                       # rendered message, {repo} and {repo_path} name the
+                                              # repo of the batch. cwd is optional.
+    author_command = ["who-am-i"]             # optional: prints the route of whoever runs
+                                              # `margin link`; their documents' comments go there
+
+    [[repo]]
+    name = "my-project"                       # becomes the Outline collection
+    path = "~/code/my-project"
+    include = ["**/*.md"]
+    exclude = ["**/node_modules/**"]
+    route = "my-project"                      # passed to the notifier as {route}
+    routes = { "docs/design/" = "design" }    # optional: by path prefix, longest wins
+                                              # A document no route names goes to whoever last
+                                              # linked it (author_command), else to `route`.
+
+Secrets are never written in the file. Each one is the output of a command.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_PATH = Path(os.environ.get("MARGIN_CONFIG", "~/.config/margin/config.toml")).expanduser()
+DEFAULT_STATE = Path(os.environ.get("MARGIN_STATE", "~/.local/state/margin/margin.db")).expanduser()
+
+ALWAYS_EXCLUDE = ["**/.git/**", "**/node_modules/**", "**/.venv/**", "**/venv/**",
+                  "**/__pycache__/**", "**/.playwright-mcp/**", "**/dist/**", "**/build/**",
+                  "**/.pytest_cache/**", "**/.mypy_cache/**", "**/.ruff_cache/**", "**/.tox/**",
+                  "**/*.egg-info/**", "**/.eggs/**", "**/.history/**", "**/site-packages/**"]
+
+
+@dataclass
+class Repo:
+    name: str
+    path: Path
+    include: list[str] = field(default_factory=lambda: ["**/*.md"])
+    exclude: list[str] = field(default_factory=list)
+    route: str = ""
+    routes: dict[str, str] = field(default_factory=dict)
+
+    def route_for(self, path: str) -> str:
+        """The route for a repo-relative path: the longest matching prefix, else the repo's."""
+        return self.named_route(path) or self.route
+
+    def named_route(self, path: str) -> str | None:
+        """The route `routes` names for a path (the longest matching prefix), or None."""
+        best = ""
+        for prefix in self.routes:
+            if (path == prefix or path.startswith(prefix.rstrip("/") + "/")) and len(prefix) > len(best):
+                best = prefix
+        return self.routes[best] if best else None
+
+
+@dataclass
+class Config:
+    url: str
+    api_key_command: list[str]
+    admin_key_command: list[str] | None
+    pin_ip_command: list[str] | None
+    listen: str
+    webhook_url: str
+    secret_command: list[str] | None
+    poll_seconds: int
+    quiet_seconds: int
+    cap_seconds: int
+    notify_command: list[str] | None
+    notify_cwd: Path | None
+    mcp_url: str | None
+    author_command: list[str] | None
+    repos: list[Repo]
+    state: Path
+
+    def run(self, argv: list[str]) -> str:
+        return subprocess.check_output(argv, text=True).strip()
+
+    def api_key(self) -> str:
+        return self.run(self.api_key_command)
+
+    def secret(self) -> str | None:
+        return self.run(self.secret_command) if self.secret_command else None
+
+    def author(self) -> str | None:
+        """The route of whoever runs margin now (author_command), or None when there is no such
+        command or it does not answer. Never raises: publishing does not depend on it."""
+        if not self.author_command:
+            return None
+        try:
+            out = subprocess.run(self.author_command, capture_output=True, text=True, timeout=20,
+                                 cwd=str(self.notify_cwd) if self.notify_cwd else None)
+        except (OSError, subprocess.SubprocessError):
+            return None
+        name = (out.stdout or "").strip().splitlines()
+        return name[0].strip() if out.returncode == 0 and name and name[0].strip() else None
+
+    def repo(self, name: str) -> Repo:
+        for r in self.repos:
+            if r.name == name:
+                return r
+        raise KeyError(f"no repo named {name!r} in the config")
+
+
+def load(path: Path = DEFAULT_PATH) -> Config:
+    raw = tomllib.loads(path.read_text())
+    o, i, b, n = (raw.get(k, {}) for k in ("outline", "intake", "batch", "notify"))
+    repos = [Repo(name=r["name"], path=Path(r["path"]).expanduser(),
+                  include=r.get("include", ["**/*.md"]), exclude=r.get("exclude", []),
+                  route=r.get("route", r["name"]), routes=r.get("routes", {}))
+             for r in raw.get("repo", [])]
+    names = [r.name for r in repos]
+    if len(names) != len(set(names)):
+        raise ValueError("two [[repo]] entries share a name")
+    return Config(
+        url=o["url"], api_key_command=o["api_key_command"],
+        admin_key_command=o.get("admin_key_command"), pin_ip_command=o.get("pin_ip_command"),
+        listen=i.get("listen", "127.0.0.1:8771"), webhook_url=i.get("webhook_url", ""),
+        secret_command=i.get("secret_command"), poll_seconds=int(i.get("poll_seconds", 600)),
+        quiet_seconds=int(b.get("quiet_seconds", 180)), cap_seconds=int(b.get("cap_seconds", 900)),
+        notify_command=n.get("command"),
+        notify_cwd=Path(n["cwd"]).expanduser() if n.get("cwd") else None,
+        mcp_url=o.get("mcp_url"), repos=repos, author_command=n.get("author_command"),
+        state=Path(raw.get("state", DEFAULT_STATE)).expanduser())
+
+
+def locate(cfg: Config, file: Path) -> tuple[Repo, str, Path] | None:
+    """repo_of, and also a file in another git worktree of a configured repo: (repo, the file's
+    repo-relative path, the folder that path is relative to). Every chat works in its own worktree,
+    so a file there is found through git's common directory, which names the main checkout."""
+    hit = repo_of(cfg, file)
+    if hit:
+        return hit[0], hit[1], hit[0].path.resolve()
+    import subprocess
+    f = file.expanduser().resolve()
+    try:
+        r = subprocess.run(["git", "-C", str(f.parent), "rev-parse", "--path-format=absolute",
+                            "--show-toplevel", "--git-common-dir"],
+                           capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    lines = r.stdout.splitlines()
+    if r.returncode != 0 or len(lines) < 2:
+        return None
+    top, main = Path(lines[0]).resolve(), Path(lines[1]).resolve().parent
+    best = None
+    for repo in cfg.repos:
+        root = repo.path.resolve()
+        if root != main and main not in root.parents:
+            continue                       # not this git repository
+        here = top / root.relative_to(main)  # the configured folder, inside the worktree
+        if f == here or here in f.parents:
+            if best is None or len(here.parts) > len(best[2].parts):
+                best = (repo, f.relative_to(here).as_posix(), here)
+    return best
+
+
+def repo_of(cfg: Config, file: Path) -> tuple[Repo, str] | None:
+    """The configured repo a file lives in, and its repo-relative path. The deepest repo wins."""
+    f = file.expanduser().resolve()
+    best = None
+    for r in cfg.repos:
+        root = r.path.resolve()
+        if f == root or root in f.parents:
+            if best is None or len(root.parts) > len(best[0].path.resolve().parts):
+                best = (r, f.relative_to(root).as_posix())
+    return best