lockmaster 0.0.1__py3-none-any.whl

lockmaster/generated.py

@@ -0,0 +1,65 @@
+"""Generated files are never merged, only rebuilt — SR-ARCHITECTURE decision 9.
+
+`lockmaster.toml` `[generated]` maps a path or glob to the command that
+rebuilds it. `regen` restores each such file to `main`'s version, then runs
+its command; a command that fails fails the run.
+
+A generated file with uncommitted edits is not overwritten: that would be
+`checkout --` over changes (SR-LAW-3 decision 3). It is refused, by name, and
+nothing is touched until it is committed or put back.
+"""
+import subprocess
+from pathlib import Path
+
+from lockmaster import git
+from lockmaster.repo import LockmasterError, matches
+
+
+class RegenError(LockmasterError):
+    pass
+
+
+def _tracked(worktree, ref, pattern):
+    names = git.run(["ls-tree", "-r", "--name-only", "-z", ref], worktree).split("\0")
+    return [n for n in names if n and matches(n, pattern)]
+
+
+def regen(worktree, config, ref=None):
+    """Rebuild every [generated] path in `worktree`. Returns the patterns rebuilt."""
+    worktree = Path(worktree)
+    ref = ref or config.main
+    if not config.generated:
+        return []
+    restore, refused = [], []
+    for pattern in config.generated:
+        for name in _tracked(worktree, ref, pattern):
+            if git.run(["status", "--porcelain", "--", name], worktree).strip():
+                refused.append(name)
+            else:
+                restore.append(name)
+    if refused:
+        raise RegenError("generated files with uncommitted edits — commit them or put them back, "
+                         "then run again: " + ", ".join(refused))
+    for name in restore:
+        blob = subprocess.run(["git", "show", ref + ":" + name], cwd=str(worktree),
+                              capture_output=True, check=True).stdout
+        target = worktree / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if not target.exists() or target.read_bytes() != blob:
+            target.write_bytes(blob)
+    done = []
+    for pattern, command in config.generated.items():
+        r = subprocess.run(command, shell=True, cwd=str(worktree), capture_output=True, text=True)
+        if r.returncode != 0:
+            tail = (r.stdout + r.stderr).strip().splitlines()[-15:]
+            raise RegenError("rebuilding `{}` with `{}` exited {}:\n  {}".format(
+                pattern, command, r.returncode, "\n  ".join(tail)))
+        done.append(pattern)
+    return done
+
+
+def stage(worktree, config):
+    """Stage whatever the rebuild changed under the [generated] patterns."""
+    for pattern in config.generated:
+        spec = ":(glob)" + pattern if any(c in pattern for c in "*?[") else pattern
+        git.run(["add", "-A", "--", spec], worktree, check=False)

lockmaster/git.py

@@ -0,0 +1,102 @@
+"""Thin wrappers over the `git` command — SR-ARCHITECTURE decision 1.
+
+Every git operation lockmaster runs goes through `run`, so the forbidden forms
+of SR-LAW-3 decision 3 have one place to be kept out of. Nothing here forces.
+"""
+import os
+import subprocess
+import time
+
+#: `-c core.hooksPath=…` while a Repo is open: lockmaster's own git steps run the
+#: repository's gate hooks and not its post-* hooks (SR-ARCHITECTURE decision 18).
+HOOKS = []
+
+
+class GitError(Exception):
+    """A git command exited non-zero."""
+
+    def __init__(self, args, code, out, err):
+        self.args_ = args
+        self.code = code
+        self.out = out
+        self.err = err
+        super().__init__("git {} exited {}: {}".format(" ".join(args), code, (err or out).strip()))
+
+
+def run(args, cwd, check=True, env=None, input=None):
+    """Run `git <args>` in `cwd`; return stdout. With check=False, return
+    (code, stdout, stderr) instead of raising."""
+    # No optional locks: a `git status` that refreshes the index takes
+    # index.lock and removes it, which a surface that cannot unlink (the
+    # Cowork bridge) would leave behind (SR-ARCHITECTURE decision 19).
+    full_env = dict(os.environ, GIT_OPTIONAL_LOCKS="0")
+    if env:
+        full_env.update(env)
+    r = subprocess.run(["git"] + HOOKS + list(args), cwd=str(cwd), capture_output=True, text=True,
+                       env=full_env, input=input)
+    if not check:
+        return r.returncode, r.stdout, r.stderr
+    if r.returncode != 0:
+        raise GitError(list(args), r.returncode, r.stdout, r.stderr)
+    return r.stdout
+
+
+def out(args, cwd, env=None):
+    """stdout of a git command, stripped."""
+    return run(args, cwd, env=env).strip()
+
+
+def ok(args, cwd):
+    """True when the git command exits 0."""
+    return run(args, cwd, check=False)[0] == 0
+
+
+def worktree_add(args, cwd, tries=8):
+    """`git worktree add -q <args>`. Retried when git trips on another worktree
+    being added at that moment: it reads the other's half-written files under
+    `.git/worktrees/` and dies (SR-LAW-8 — no caller is refused for that). A
+    `-b <branch>` attempt that died after creating the branch is retried
+    without `-b`, on the branch it made."""
+    args = list(args)
+    for attempt in range(tries):
+        code, o, e = run(["worktree", "add", "-q"] + args, cwd, check=False)
+        if code == 0:
+            return
+        if ".git/worktrees/" not in e or attempt == tries - 1:
+            raise GitError(["worktree", "add", "-q"] + args, code, o, e)
+        if "-b" in args:
+            i = args.index("-b")
+            branch, path, start = args[i + 1], args[i + 2], args[i + 3]
+            head = run(["rev-parse", "--verify", "--quiet", "refs/heads/" + branch], cwd, check=False)
+            held = any(t["branch"] == branch for t in worktrees(cwd))
+            if head[0] == 0 and not held and head[1].strip() == run(["rev-parse", start], cwd).strip():
+                args = [path, branch]
+        time.sleep(0.05 * (attempt + 1))
+
+
+def worktrees(cwd):
+    """Every worktree of the repository: dicts of path, head, branch, locked."""
+    trees, cur = [], None
+    for line in run(["worktree", "list", "--porcelain"], cwd).splitlines() + [""]:
+        if not line:
+            if cur:
+                trees.append(cur)
+            cur = None
+            continue
+        key, _, val = line.partition(" ")
+        if key == "worktree":
+            cur = {"path": val, "head": "", "branch": "", "locked": None}
+        elif cur is None:
+            continue
+        elif key == "HEAD":
+            cur["head"] = val
+        elif key == "branch":
+            cur["branch"] = val[len("refs/heads/"):] if val.startswith("refs/heads/") else val
+        elif key == "locked":
+            cur["locked"] = val
+    return trees
+
+
+def dirty(cwd):
+    """`git status --porcelain` lines: modified, staged, deleted or untracked."""
+    return [l for l in run(["status", "--porcelain", "--untracked-files=all"], cwd).splitlines() if l]

lockmaster/install.py

@@ -0,0 +1,229 @@
+"""`lockmaster install <repo>` — SR-ARCHITECTURE decisions 14 and 15.
+
+    kit/claude/**  ->  <repo>/.claude/**   hooks made executable
+    kit/github/**  ->  <repo>/.github/**   (none today: a repository's CI is its own)
+    kit/claude/settings.json is MERGED into <repo>/.claude/settings.json: the
+        kit's hook entries replace the ones a previous install wrote; the
+        repo's own entries and keys are kept
+    <repo>/.claude/lockmaster.lock  records the version, the kit's digest and
+        each installed file's hash, so `lockmaster doctor` sees a mismatch
+    the merge drivers, when the repo has a lockmaster.toml
+    kit/work/<file>  ->  <repo>/work/<file>  for each of the six work files the
+        repo lacks (SR-LAW-10 decision 6); one that exists is never touched,
+        and they are the project's own papers, not kit files (decision 16)
+
+An existing file the kit would replace, and which a previous install did not
+write, is never overwritten silently: the install stops and names it, or with
+--backup moves it aside to `<file>.pre-lockmaster` first (SR-LAW-3).
+"""
+import hashlib
+import json
+import os
+import stat
+from pathlib import Path
+
+from lockmaster import __version__
+from lockmaster import git
+from lockmaster.repo import LockmasterError
+
+LOCK = ".claude/lockmaster.lock"
+SETTINGS = ".claude/settings.json"
+TREES = (("claude", ".claude"), ("github", ".github"))
+# SR-LAW-10: the six work files every repository lockmaster is installed in keeps.
+WORK_FILES = ("OPEN-WORK.md", "BACKLOG.md", "INTERVIEW.md", "MACHINE.md", "LESSONS.md", "WORKLOG.md")
+
+
+def find_kit():
+    """The kit this lockmaster carries: $LOCKMASTER_KIT, the package's own
+    copy, or the source checkout's kit/."""
+    env = os.environ.get("LOCKMASTER_KIT")
+    here = Path(__file__).resolve().parent
+    for cand in ([Path(env)] if env else []) + [here / "kit", here.parents[1] / "kit"]:
+        if (cand / "claude").is_dir():
+            return cand
+    raise LockmasterError("cannot find the kit (set LOCKMASTER_KIT to a kit/ directory)")
+
+
+def sha(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def kit_files(kit):
+    """(source path, installed relative path) for every kit file but settings.json."""
+    out = []
+    for sub, dest in TREES:
+        base = kit / sub
+        if not base.is_dir():
+            continue
+        for f in sorted(base.rglob("*")):
+            if f.is_dir() or "__pycache__" in f.parts or f.name == ".DS_Store":
+                continue
+            rel = (Path(dest) / f.relative_to(base)).as_posix()
+            if rel != SETTINGS:
+                out.append((f, rel))
+    return out
+
+
+def kit_digest(kit):
+    h = hashlib.sha256()
+    for f, rel in kit_files(kit) + [(kit / "claude" / "settings.json", SETTINGS)]:
+        if f.is_file():
+            h.update(rel.encode() + b"\0" + f.read_bytes() + b"\0")
+    return h.hexdigest()
+
+
+def read_lock(target):
+    try:
+        return json.loads((Path(target) / LOCK).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _commands(settings):
+    return {h.get("command") for groups in settings.get("hooks", {}).values()
+            for g in groups for h in g.get("hooks", []) if h.get("command")}
+
+
+def merge_settings(current, kit_settings, managed_before):
+    """The kit's hook entries, then the repo's own; every other key of the
+    repo's settings kept. `managed_before` are the commands a previous install
+    wrote, so a hook the kit dropped leaves too."""
+    managed = set(managed_before) | _commands(kit_settings)
+    merged = dict(current)
+    for key, value in kit_settings.items():
+        if key != "hooks" and key not in merged:
+            merged[key] = value
+    hooks = {}
+    events = list(kit_settings.get("hooks", {})) + [e for e in current.get("hooks", {})
+                                                     if e not in kit_settings.get("hooks", {})]
+    for event in events:
+        own = []
+        for g in current.get("hooks", {}).get(event, []):
+            kept = [h for h in g.get("hooks", []) if h.get("command") not in managed]
+            if kept:
+                own.append(dict(g, hooks=kept))
+        groups = list(kit_settings.get("hooks", {}).get(event, [])) + own
+        if groups:
+            hooks[event] = groups
+    merged["hooks"] = hooks
+    return merged
+
+
+def install(target, backup=False, out=print):
+    target = Path(target).resolve()
+    if git.run(["rev-parse", "--show-toplevel"], target, check=False)[0] != 0:
+        raise LockmasterError("not a git repository: {}".format(target))
+    kit = find_kit()
+    old = read_lock(target)
+    old_files = old.get("files", {})
+    plan = kit_files(kit)
+
+    conflicts = []
+    for src, rel in plan:
+        dst = target / rel
+        if dst.exists():
+            cur = sha(dst)
+            if cur != sha(src) and old_files.get(rel) != cur:
+                conflicts.append(rel)
+    if conflicts and not backup:
+        raise LockmasterError(
+            "these files exist and were not written by a lockmaster install; nothing was changed:\n  "
+            + "\n  ".join(conflicts)
+            + "\nrun again with --backup to move each aside to <file>.pre-lockmaster first")
+    for rel in conflicts:
+        dst = target / rel
+        aside, n = dst.with_name(dst.name + ".pre-lockmaster"), 1
+        while aside.exists():
+            aside, n = dst.with_name("{}.pre-lockmaster.{}".format(dst.name, n)), n + 1
+        os.rename(str(dst), str(aside))
+        out("  moved aside: {} -> {}".format(rel, aside.relative_to(target).as_posix()))
+
+    files = {}
+    for src, rel in plan:
+        dst = target / rel
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        data = src.read_bytes()
+        if not dst.exists() or dst.read_bytes() != data:
+            dst.write_bytes(data)
+        if "hooks" in Path(rel).parts and dst.suffix in (".sh", ".py"):
+            dst.chmod(dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        files[rel] = sha(dst)
+
+    # A file an earlier kit installed and this one does not: removed only if untouched.
+    for rel, digest in old_files.items():
+        dst = target / rel
+        if rel not in files and dst.is_file():
+            if sha(dst) == digest:
+                dst.unlink()
+                out("  removed (no longer in the kit): " + rel)
+            else:
+                out("  kept, edited by hand and no longer in the kit: " + rel)
+
+    kit_settings = json.loads((kit / "claude" / "settings.json").read_text(encoding="utf-8"))
+    settings_path = target / SETTINGS
+    current = json.loads(settings_path.read_text(encoding="utf-8")) if settings_path.is_file() else {}
+    merged = merge_settings(current, kit_settings, old.get("settings", []))
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(merged, indent=2, ensure_ascii=False) + "\n"
+    if not settings_path.is_file() or settings_path.read_text(encoding="utf-8") != text:
+        settings_path.write_text(text, encoding="utf-8")
+
+    lock = {"version": __version__, "kit": kit_digest(kit), "files": files,
+            "settings": sorted(_commands(kit_settings))}
+    (target / LOCK).write_text(json.dumps(lock, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    out("installed kit {} into {}: {} files, settings merged".format(lock["kit"][:12], target, len(files)))
+
+    from lockmaster.repo import Repo
+    from lockmaster import drivers
+    repo = Repo(target)
+    if (target / "lockmaster.toml").is_file():
+        from lockmaster import surface
+        if surface.foreign(repo) or not surface.can_unlink(repo):
+            # Decision 10: a driver registered here would name this surface's
+            # paths; the machine that commits registers it on its first landing.
+            if drivers.write_attributes(repo.root, repo.config.merge):
+                out("  .gitattributes: lockmaster's [merge] block written — commit it")
+            out("  merge drivers not registered from here: the next landing on the machine that commits does it")
+        else:
+            if drivers.install(repo):
+                out("  .gitattributes: lockmaster's [merge] block written — commit it")
+            out("  merge drivers registered in .git/config")
+    made = work_files(target, kit)
+    if made:
+        out("  work files created (SR-LAW-10) — commit them: " + ", ".join("work/" + f for f in made))
+    _guard(repo, out)
+    return lock
+
+
+def work_files(target, kit):
+    """Write each of the six work files `target` lacks from the kit's template.
+    Never overwrites; returns the names written."""
+    made = []
+    for name in WORK_FILES:
+        dst = Path(target) / "work" / name
+        src = kit / "work" / name
+        if dst.exists() or dst.is_symlink() or not src.is_file():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(str(dst), "xb") as fh:  # exclusive: a file written meanwhile is kept
+                fh.write(src.read_bytes())
+        except FileExistsError:
+            continue
+        made.append(name)
+    return made
+
+
+def _guard(repo, out):
+    """The commit guard, when the repository carries scripts/sr-guard.sh (SR-WORK-OWNERSHIP decision 6)."""
+    guard = repo.root / "scripts" / "sr-guard.sh"
+    if not guard.is_file():
+        return
+    guard.chmod(guard.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    hooks = repo.common / "hooks"
+    hooks.mkdir(exist_ok=True)
+    link = hooks / "commit-msg"
+    if link.is_symlink() or link.exists():
+        return
+    os.symlink(os.path.relpath(str(guard), str(hooks)), str(link))
+    out("  commit guard: .git/hooks/commit-msg -> scripts/sr-guard.sh")

lockmaster/kit/claude/hooks/auto-land.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Auto-landing — SR-ARCHITECTURE decisions 19 and 20: finished work reaches main
+without anyone remembering to land it, and what Cowork could not commit,
+Claude Code does.
+
+    start  SessionStart      export CLAUDE_SESSION_ID for this session's commands,
+                             so `lockmaster start` records whose change it is;
+                             land waiting handoffs in the background
+    edit   PostToolUse       note each file this session writes in main's checkout
+    stop   Stop              say what earlier landings did (and, once, a landing
+                             waiting on main's checkout); tell the agent, once,
+                             about a landing held back, a handoff that did not
+                             land, or edits left in main's checkout; then land
+                             this session's open changes (they stay open) and
+                             the handoffs, in the background
+    end    SessionEnd        land and clean up this session's changes, in the
+                             background (the session is going away)
+
+lockmaster is found at `$LOCKMASTER_SRC`, in this repository's own `src/`
+(lockmaster itself), in a `lockmaster` checkout beside this repository, or as
+an installed package. Without it the hook does nothing.
+It never fails a session: every error is swallowed and the turn ends as usual.
+Python >= 3.9, standard library only.
+"""
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def git(args, cwd):
+    try:
+        r = subprocess.run(["git"] + args, cwd=str(cwd), capture_output=True, text=True)
+    except OSError:
+        return None
+    return r.stdout.strip() if r.returncode == 0 else None
+
+
+def main_root(cwd):
+    """The primary checkout: the first `git worktree list` entry."""
+    out = git(["worktree", "list", "--porcelain"], cwd)
+    if not out:
+        return None
+    return Path(out.splitlines()[0][len("worktree "):])
+
+
+def candidates():
+    env = os.environ.get("LOCKMASTER_SRC")
+    if env:
+        yield Path(env)
+    yield ROOT / "src"
+    root = main_root(ROOT)
+    if root is not None:
+        yield root / "src"
+        yield root.parent / "lockmaster" / "src"
+
+
+def find_src():
+    """The directory to put on sys.path, "" when lockmaster is installed, None when absent."""
+    for c in candidates():
+        if (c / "lockmaster" / "land.py").is_file():
+            return str(c)
+    try:
+        import lockmaster  # noqa: F401
+        return ""
+    except ImportError:
+        return None
+
+
+def load():
+    src = find_src()
+    if src is None:
+        return None, None
+    if src:
+        sys.path.insert(0, src)
+    from lockmaster import land
+    from lockmaster.repo import Repo
+    return src, (land, Repo)
+
+
+def command(src):
+    return "PYTHONPATH={} python3 -m lockmaster".format(src) if src else "lockmaster"
+
+
+def detach(src, args, cwd):
+    """Run `lockmaster <args>` on its own, outliving this hook; output to the state dir's log."""
+    common = git(["rev-parse", "--git-common-dir"], cwd)
+    if not common:
+        return
+    log_dir = (Path(cwd) / common).resolve() / "lockmaster"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    env = dict(os.environ)
+    if src:
+        env["PYTHONPATH"] = src + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")
+    with open(str(log_dir / "auto-land.log"), "a", encoding="utf-8") as log:
+        subprocess.Popen([sys.executable, "-m", "lockmaster"] + args, cwd=str(cwd), env=env,
+                         stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True)
+
+
+# ---------------------------------------------------------------- the session's own notes
+
+def notes_file(repo, sid):
+    safe = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in sid)
+    return repo.state / "sessions" / (safe + ".json")
+
+
+def read_notes(repo, sid):
+    try:
+        return json.loads(notes_file(repo, sid).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {"edits": []}
+
+
+def write_notes(repo, sid, notes):
+    f = notes_file(repo, sid)
+    f.parent.mkdir(parents=True, exist_ok=True)
+    tmp = f.with_name(f.name + ".part")
+    tmp.write_text(json.dumps(notes, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(str(tmp), str(f))
+
+
+# ---------------------------------------------------------------- modes
+
+def start(sid, hook):
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    if env_file and sid:
+        with open(env_file, "a", encoding="utf-8") as fh:
+            fh.write("export CLAUDE_SESSION_ID={}\n".format(sid))
+    src = find_src()
+    if src is not None:
+        detach(src, ["pickup"], hook.get("cwd") or ROOT)
+    return None
+
+
+def edit(sid, hook):
+    raw = (hook.get("tool_input") or {}).get("file_path") or (hook.get("tool_input") or {}).get("notebook_path")
+    if not raw or not sid:
+        return None
+    src, mods = load()
+    if mods is None:
+        return None
+    _, Repo = mods
+    p = Path(raw)
+    if not p.is_absolute():
+        p = Path(hook.get("cwd") or os.getcwd()) / p
+    repo = Repo(hook.get("cwd") or ROOT)
+    root = os.path.realpath(str(repo.root))
+    full = os.path.realpath(str(p))
+    if not full.startswith(root + os.sep):
+        return None
+    rel = os.path.relpath(full, root).replace(os.sep, "/")
+    if rel.startswith(".claude/worktrees/") or repo.change_holding(full) is not None:
+        return None
+    notes = read_notes(repo, sid)
+    if rel not in notes["edits"]:
+        notes["edits"].append(rel)
+        write_notes(repo, sid, notes)
+    return None
+
+
+def stop(sid, hook):
+    """Report what earlier landings did, then land in the background: a
+    landing runs the repository's checks and rebuilds, which can take minutes
+    (fux), so a turn never waits on it. `LOCKMASTER_FOREGROUND=1` lands first
+    and reports at once (the tests)."""
+    src, mods = load()
+    if mods is None:
+        return None
+    land, Repo = mods
+    cwd = hook.get("cwd") or str(ROOT)
+    said, lines = [], []
+
+    def step(fn):
+        """Each step on its own: one failing never skips the others."""
+        try:
+            return fn()
+        except Exception as e:  # noqa: BLE001
+            print("auto-land.py stop: {}".format(e), file=sys.stderr)
+            return None
+
+    foreground = os.environ.get("LOCKMASTER_FOREGROUND") == "1"
+    if foreground:
+        step(lambda: land.sync(Repo(cwd), session=sid, cwd=cwd, out=lines.append))
+        step(lambda: land.pickup(Repo(cwd), out=lines.append))
+    repo = step(lambda: Repo(cwd))
+    if repo is None:
+        return None
+    notes = read_notes(repo, sid) if sid else {"edits": []}
+    since = notes.get("last_stop", 0)
+    landed = []
+    for c in step(repo.changes) or []:
+        if (c.get("landed_at") or 0) > since and land._mine(c, sid, cwd):
+            landed.append("landed {} as {}".format(c["item"], (c.get("landed") or "")[:10]))
+    # W-10: a landing waiting on main's checkout lands by itself; it is said, never blocks.
+    for item, reason in step(lambda: getattr(land, "waiting_reports", lambda *a, **k: [])(
+            repo, session=sid, cwd=cwd)) or []:
+        landed.append("{} is waiting: {}".format(item, reason))
+    told = notes.setdefault("told_handoffs", {})
+    for h in step(lambda: land.handoffs(repo)) or []:
+        if h.get("reason") and told.get(h["item"]) != h.get("tried"):
+            told[h["item"]] = h.get("tried")
+            said.append("Edits handed over from Cowork ({}) did not land:\n{}\nFix them where they are, in "
+                        "main's checkout; the end of the next turn tries again with them.".format(
+                            h["item"], h["reason"]))
+    for item, reason in step(lambda: land.held_reports(repo, session=sid, cwd=cwd)) or []:
+        said.append("lockmaster could not land {} at the end of a turn:\n{}\nFix it in its worktree; it "
+                    "lands at the end of the next turn. Nothing on main changed.".format(item, reason))
+    if sid:
+        notes["last_stop"] = time.time()
+        write_notes(repo, sid, notes)
+        reminder = step(lambda: checkout_reminder(land, repo, sid, src))
+        if reminder:
+            said.append(reminder)
+    if not foreground:
+        args = ["sync", "--pickup", "--cwd", cwd] + (["--session", sid] if sid else [])
+        step(lambda: detach(src, args, cwd))
+    result = {}
+    if landed:
+        result["systemMessage"] = "lockmaster: " + "; ".join(landed)
+    if said:
+        if hook.get("stop_hook_active"):
+            # Already continuing because of a Stop hook: say it, never block twice in a row.
+            result["systemMessage"] = "\n\n".join(([result["systemMessage"]] if landed else []) + said)
+        else:
+            result["decision"] = "block"
+            result["reason"] = "\n\n".join(said)
+    return result or None
+
+
+def checkout_reminder(land, repo, sid, src):
+    """Once per set of files: the session's own edits in main's checkout that are not on main."""
+    notes = read_notes(repo, sid)
+    if not notes["edits"]:
+        return None
+    left = [p for p in land._checkout_dirty(repo, notes["edits"]) if p in notes["edits"]]
+    if not left:
+        return None
+    key = hashlib.sha256("\0".join(sorted(left)).encode()).hexdigest()[:16]
+    if notes.get("told") == key:
+        return None
+    notes["told"] = key
+    write_notes(repo, sid, notes)
+    return ("This session edited {} in main's checkout and it is not on main. Land it now: "
+            "`{} save -m \"<what changed and why>\" {}`".format(", ".join(left), command(src), " ".join(left)))
+
+
+def end(sid, hook):
+    src = find_src()
+    if src is None:
+        return None
+    cwd = hook.get("cwd") or str(ROOT)
+    args = ["sync", "--final", "--cwd", cwd] + (["--session", sid] if sid else [])
+    detach(src, args, cwd)
+    return None
+
+
+def main(argv):
+    mode = argv[0] if argv else ""
+    fn = {"start": start, "edit": edit, "stop": stop, "end": end}.get(mode)
+    if fn is None:
+        print("usage: auto-land.py start|edit|stop|end", file=sys.stderr)
+        return 0
+    hook = {}
+    if not sys.stdin.isatty():
+        try:
+            hook = json.loads(sys.stdin.read() or "{}")
+        except ValueError:
+            hook = {}
+    sid = hook.get("session_id") or os.environ.get("CLAUDE_SESSION_ID", "")
+    try:
+        result = fn(sid, hook)
+    except Exception as e:  # noqa: BLE001 — never fail the session over a landing
+        print("auto-land.py {}: {}".format(mode, e), file=sys.stderr)
+        return 0
+    if result:
+        print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))