@nidvue/teamwork 1.1.1 → 1.4.2

package/skills/teamwork/src/teamwork/engine.py

@@ -22,7 +22,8 @@ Usage
     teamwork.py load AGENT [--limit N]
     teamwork.py remember AGENT TEXT [--layer short|long] [--key K]
                                   [--importance 0-5] [--tags a,b] [--pin]
-    teamwork.py global TEXT [--key K] [--importance N] [--tags a,b] [--pin]
+    teamwork.py global TEXT [--by BY] [--src SRC] [--rev REV]
+                            [--key K] [--importance N] [--tags a,b] [--pin]
     teamwork.py recall QUERY [--agent A] [--all] [--global] [--layer both|short|long]
     teamwork.py touch AGENT ID|KEY [--layer short|long]
     teamwork.py forget AGENT ID|KEY [--layer short|long]
@@ -107,12 +108,17 @@ from .config import (
     LAYER_CELL,
     LAYER_OWNER,
     LAYER_WHAT,
+    LFS_MAX_BYTES,
     LONG_CAP,
     MAX_ROUNDS,
+    MEMORY_ARBITER_ROLE,
+    MEMORY_LEASE_MINUTES,
+    MEMORY_STALL_MINUTES,
     MIN_USES,
     PRIORITY_ORDER,
     PROMOTE_MIN_IMPORTANCE,
     REVIEW_FAIL_LIMIT,
+    REVIEW_LEASE_MINUTES,
     REVIEW_STATUSES,
     ROLE_PARENT,
     ROLE_REPORT_ORDER,
@@ -149,7 +155,9 @@ from .gitutil import (
     branch_worktree,
     current_branch,
     ensure_lfs,
+    is_binary_content,
     is_git_repo,
+    lfs_text_mismatch,
     lfs_tracked,
     run_git,
 )
@@ -196,9 +204,9 @@ from .layout import (
     task_file,
     team_root_from,
     team_root_from_cwd,
-    teams_root_unused,
     testplan_path,
     tests_path,
+    work_docs_dir,
     work_repo,
 )
 from .names import (
@@ -380,9 +388,9 @@ __all__ = [
     "project_of",
     "docs_dir",
     "work_repo",
+    "work_docs_dir",
     "team_root_from_cwd",
     "project_root",
-    "teams_root_unused",
     "agents_dir",
     "agent_dir",
     "roles_dir",
@@ -419,6 +427,7 @@ __all__ = [
     "branch_merged",
     "branch_worktree",
     "ensure_lfs",
+    "lfs_text_mismatch",
     "lfs_tracked",
     "branch_name",
     "REVIEWS_HEADER",
@@ -1377,6 +1386,8 @@ def _pr_open(args, root: Path, project: Path, here: Path, path: Path, role: str)
     )
     print(f"# {pr['id']} open: {pr['title']}")
     print(f"#   branch {pr['branch']} -> {pr['base']}   author {pr['author']}")
+    profile, reason = review_profile_for(root, role, t)
+    print(f"#   review profile: {profile} ({reason})   (packet: review {role} {t['id']} --packet)")
     if pushed:
         print(f"#   {pushed}")
     print(
@@ -2071,17 +2082,6 @@ def _tests_list(args, root: Path, records: list) -> int:
     return 0
 
 
-def cmd_testplan_unused(args) -> int:
-    root = project_root(args)
-    plan = parse_testplan(testplan_path(root))
-    print(f"# Test plan ({testplan_path(root)})")
-    if not plan:
-        print(f"# default required layers for any area: {', '.join(DEFAULT_REQUIRED_LAYERS)}")
-    for area in sorted(plan):
-        print(f"- {area:20s} {', '.join(plan[area])}")
-    return 0
-
-
 # --------------------------------------------------------------------------- #
 # Audit trail: append-only hash-chained ledger + provenance + external export
 #
@@ -2104,6 +2104,15 @@ LEDGER_ACTIONS = (
     "memory.drop",
     "memory.merge",
     "memory.evict",
+    "memory.claim",
+    "memory.claim.force",
+    "memory.renew",
+    "memory.release",
+    "memory.contest",
+    "memory.grant",
+    "memory.revoke",
+    "instance.add",
+    "instance.retire",
     "task.add",
     "task.claim",
     "task.status",
@@ -2375,7 +2384,7 @@ def ledger_verify(root: Path, reconcile: bool = False, _locked: bool = False) ->
         except (ValueError, OSError, TypeError):
             problems.append("head cache is unreadable")
     # external anchor: the last exported checkpoint must not be ahead of us
-    manifest = docs_dir(root) / F_MANIFEST
+    manifest = work_docs_dir(root) / F_MANIFEST
     if manifest.exists():
         try:
             import json
@@ -2790,37 +2799,50 @@ def _file_digest(path: Path) -> str:
         return ""
 
 
-def manifest_path_hint(root: Path) -> Path:
-    return docs_dir(root) / F_MANIFEST
-
-
 def ledger_export(root: Path, args) -> int:
-    """Emit an externally verifiable manifest of the whole trail."""
+    """Emit an externally verifiable manifest of the whole trail.
+
+    The manifest is project output, so it is written in the work tree the
+    command acts on: a lane that exports from its own worktree gets a file it
+    can commit on its branch, and the manifest describes that work tree's
+    revision. Writing it into the project that owns the team tree instead left
+    the lane's worktree clean and the main checkout dirty - the very state the
+    manifest's own ``dirty`` field then misreported - and pinned the main
+    checkout's head, a revision the committing branch does not have.
+    """
     import json
 
-    project = project_of(root)
+    # The work tree the command acts on: a lane that exports from its own
+    # worktree gets a file it can commit on its branch, and the manifest
+    # describes that work tree's revision.
+    project = work_repo(root)
+    docs = work_docs_dir(root)
+    # The team's hidden tree (ledger, memory, task queues) lives in the project
+    # that owns it, not in the work tree, so its entries stay relative to that
+    # project.
+    state_root = project_of(root)
     problems = ledger_verify(root, reconcile=True)
     records = ledger_read(root)
     tracked = []
-    for path in (
-        criteria_path(root),
-        tests_path(root),
-        testplan_path(root),
-        reviews_path(root),
-        disputes_path(root),
-        global_dir(root) / F_GLOBAL,
-        docs_dir(root) / "Project.md",
-        docs_dir(root) / "Plan.md",
-        docs_dir(root) / "Architecture.md",
-        docs_dir(root) / "Decisions.md",
-        docs_dir(root) / "Archive.md",
+    for path, base in (
+        (criteria_path(root), state_root),
+        (tests_path(root), state_root),
+        (testplan_path(root), state_root),
+        (reviews_path(root), state_root),
+        (disputes_path(root), state_root),
+        (global_dir(root) / F_GLOBAL, state_root),
+        (docs / "Project.md", project),
+        (docs / "Plan.md", project),
+        (docs / "Architecture.md", project),
+        (docs / "Decisions.md", project),
+        (docs / "Archive.md", project),
     ):
         if path.exists():
             tracked.append(
                 {
                     # posix form: the manifest is published, so a Windows
                     # backslash would make the same revision hash differently.
-                    "path": path.relative_to(project).as_posix(),
+                    "path": path.relative_to(base).as_posix(),
                     "sha256": _file_digest(path),
                     "bytes": path.stat().st_size,
                 }
@@ -2831,7 +2853,7 @@ def ledger_export(root: Path, args) -> int:
             if p.exists():
                 tracked.append(
                     {
-                        "path": p.relative_to(project).as_posix(),
+                        "path": p.relative_to(state_root).as_posix(),
                         "sha256": _file_digest(p),
                         "bytes": p.stat().st_size,
                     }
@@ -2859,7 +2881,7 @@ def ledger_export(root: Path, args) -> int:
         root,
         "ledger.export",
         export_actor,
-        str(manifest_path_hint(root)),
+        str(docs / F_MANIFEST),
         f"manifest export ({len(records)} records before this event)",
     )
     records = ledger_read(root)
@@ -2873,7 +2895,7 @@ def ledger_export(root: Path, args) -> int:
     # Archive.md is the accepted-results ledger: it gains an entry for this very
     # deliverable when the review passes, so a digest committed beside it is stale
     # by construction. Its entries are verified through the ledger, not a snapshot.
-    archive_rel = archive_path(root).relative_to(project).as_posix()
+    archive_rel = (docs / "Archive.md").relative_to(project).as_posix()
     external = [a for a in tracked if not a["path"].startswith(".pi/") and a["path"] != archive_rel]
     internal = [a for a in tracked if a["path"].startswith(".pi/")]
     manifest = {
@@ -2882,8 +2904,9 @@ def ledger_export(root: Path, args) -> int:
         "team_id": team_identity(root) or ensure_team_identity(root),
         # Never embed the absolute checkout path: the manifest is committed and
         # published, and a machine path is both a privacy leak and useless to a
-        # verifier on another host.
-        "project": project.name,
+        # verifier on another host. The name is the project's, never the work
+        # tree's: a lane worktree is named after the instance that owns it.
+        "project": state_root.name,
         "ledger": {
             "records": len(records),
             "checkpoint_n": checkpoint_n,
@@ -2911,7 +2934,7 @@ def ledger_export(root: Path, args) -> int:
             "pinned as an artifact; follow its entries with `trace`.",
         ],
     }
-    out_dir = docs_dir(root)
+    out_dir = docs
     out_dir.mkdir(parents=True, exist_ok=True)
     manifest_path = out_dir / F_MANIFEST
     report_path = out_dir / F_AUDITREPORT
@@ -3171,10 +3194,99 @@ def cmd_skill(args) -> int:
     return 0
 
 
+def guard_committer_identity(project: Path, rev_range: str = "HEAD") -> int:
+    """Fail when a commit on the default branch carries a non-role committer.
+
+    A host merge button - squash or rebase - writes the *signed-in account* into
+    the commit it creates, as author (squash) or as committer (rebase). The privacy
+    gate scans the history and fails on that personal mailbox; because the same
+    gate is an acceptance proof, the traceability guard fails with it and the
+    whole test matrix goes red. Measured on this repository: three rewrites of
+    ``main`` on 2026-10-20, all from this one cause.
+
+    This is the early signal for it: it reads the *committer* of the commits in
+    the range, so it fires the moment a merge button stamps the account, and it
+    prints the repair instead of leaving the next person to discover the red
+    build.
+
+    Accepted committers: a role mailbox of this team, the host's own noreply
+    service address, and an author whose committer was rewritten by the host
+    (the host stamp is transport, not identity - but the *author* still has to be
+    a role mailbox, which ``identity --audit`` enforces separately).
+    """
+    canonical = canonical_identities()
+    proc = run_git(
+        project, "log", "--format=%H%x1f%an%x1f%ae%x1f%cn%x1f%ce%x1f%P%x1f%B%x1e", rev_range
+    )
+    if proc.returncode != 0:
+        # A range whose base does not resolve is not a usage error: a push after a
+        # rewrite, or a pull_request event's all-zero "before", leaves exactly that.
+        # The tip is what can be measured, so measure it and say so.
+        tip = rev_range.split("..", 1)[1].strip() if ".." in rev_range else rev_range
+        print(
+            f"# {rev_range} cannot be read ({proc.stderr.strip()}); "
+            f"auditing the tip only, the span before it is unmeasurable"
+        )
+        proc = run_git(
+            project, "log", "--format=%H%x1f%an%x1f%ae%x1f%cn%x1f%ce%x1f%P%x1f%B%x1e", tip or "HEAD"
+        )
+        rev_range = tip or "HEAD"
+        if proc.returncode != 0:
+            print(f"teamwork: cannot read {rev_range}: {proc.stderr.strip()}")
+            return 2
+    problems = []
+    seen = 0
+    for record in proc.stdout.split("\x1e"):
+        record = record.strip("\n")
+        if not record:
+            continue
+        parts = record.split("\x1f")
+        if len(parts) < 5:
+            continue
+        sha, an, ae, cn, ce = parts[0], parts[1], parts[2], parts[3], parts[4]
+        subject = parts[6].splitlines()[0] if len(parts) > 6 and parts[6] else ""
+        parents = parts[5].split() if len(parts) > 5 and parts[5] else []
+        # A forge's synthetic pull-request merge ref is an artefact of the forge,
+        # not a commit anyone pushed: the host authors it as the PR author and
+        # commits it as itself, and it never lands on the default branch. Guarding
+        # it would fail every pull request on a repository that merges through the
+        # host - the same reason the identity audit skips it.
+        if len(parents) >= 2 and _RE_FORGE_MERGE_SUBJECT.match(subject.strip()):
+            print(f"- {sha[:12]} skipped: forge pull-request merge ref")
+            continue
+        seen += 1
+        if ce in canonical:
+            continue
+        if _RE_FORGE_COMMITTER_EMAIL.match(ce) and ae in canonical:
+            continue
+        problems.append((sha[:12], an, ae, cn, ce))
+    if not problems:
+        print(f"# committer guard: {seen} commit(s) in {rev_range} carry a role committer")
+        return 0
+    print(f"# committer guard: {len(problems)} commit(s) in {rev_range} carry a foreign committer")
+    for sha, an, ae, cn, ce in problems:
+        print(f"- {sha} FAIL committer {cn} <{ce}> (author {an} <{ae}>)")
+    print(
+        "# A host merge button (squash or rebase) writes the signed-in account into "
+        "the commit it creates, and the privacy gate fails on that personal mailbox "
+        "in the history."
+    )
+    print(
+        "# Repair: merge locally as the reviewing role and push - "
+        "`teamwork.py pr merge --pr <id> --by <reviewer>` commits as a role "
+        "mailbox. To repair an existing commit, amend it to a role mailbox, prove "
+        "its tree is byte-identical, and push it with --force-with-lease."
+    )
+    return 1
+
+
 def cmd_identity(args) -> int:
     root = project_root(args)
-    if args.audit:
+    if getattr(args, "guard_committer", False):
         project = project_of(root)
+        return guard_committer_identity(project, args.rev_range or "HEAD")
+    if args.audit:
+        project = audit_repository(root, args)
         return audit_commit_identities(
             project,
             args.rev_range or default_audit_range(project),
@@ -3199,6 +3311,27 @@ _RE_BOT_EMAIL = re.compile(
 )
 _RE_FORGE_MERGE_SUBJECT = re.compile(r"^Merge [0-9a-f]{40} into [0-9a-f]{40}$")
 _RE_ACTING_ROLE = re.compile(r"^Acting role:\s*(.+?)\s*$", re.MULTILINE)
+#: ``Role: <display name>`` is the same machine-written fact as ``Acting role:``:
+#: ``build_commit_message`` emits both, so a message that carries only the
+#: structured trailer still names its acting role.
+_RE_ROLE_FIELD = re.compile(r"^Role:\s*(.+?)\s*$", re.MULTILINE)
+#: The subject of a team merge commit that lands no content of its own. Both the
+#: scripted form (``chore(merge): ...``) and a plain ``git merge`` subject count,
+#: because integrating a peer branch is the same content-free act either way.
+_RE_MERGE_SUBJECT = re.compile(
+    r"^(?:"
+    r"chore\(merge\):"
+    r"|Merge branch '[^']+'(?: into [^\s]+)?"
+    r"|Merge commit '[0-9a-f]{7,40}'"
+    r")",
+    re.IGNORECASE,
+)
+#: The committer a git host stamps on a merge it performs itself. It is transport,
+#: not identity: a forge rebase merge rewrites the committer to this account and
+#: leaves the author untouched, so the role that did the work is still the author -
+#: which is what this audit checks, and what the privacy gate already accepts
+#: (``noreply@github.com`` is a service address there, never a personal mailbox).
+_RE_FORGE_COMMITTER_EMAIL = re.compile(r"^(?:noreply@github\.com|noreply@gitlab\.com)$")
 
 
 def canonical_identities() -> dict:
@@ -3206,6 +3339,26 @@ def canonical_identities() -> dict:
     return {role_identity(role)[1]: role_identity(role)[0] for role in ROLE_DISPLAY}
 
 
+def audit_repository(root: Path, args) -> Path:
+    """The repository whose history ``identity --audit`` must read.
+
+    The audit is about the branch the actor is working on, and a linked lane
+    worktree is its own work tree with its own ``HEAD``. Resolving against the
+    primary checkout (``project_of(root)``) made a worktree invocation audit
+    *main's* history and report a vacuous "0 problems" - the exact false green the
+    same command is used to avoid. So: an explicit ``--project`` wins, otherwise
+    the work tree git finds from the current directory, otherwise the project that
+    owns the team tree (the historical answer, kept for a cwd inside no repository).
+    """
+    if getattr(args, "project", None):
+        return project_path(args)
+    here = Path.cwd().resolve()
+    result = run_git(here, "rev-parse", "--show-toplevel")
+    if result.returncode == 0 and result.stdout.strip():
+        return Path(result.stdout.strip()).resolve()
+    return work_repo(root, here)
+
+
 def default_audit_range(project: Path) -> str:
     if run_git(project, "rev-parse", "--verify", "--quiet", "origin/main").returncode == 0:
         return "origin/main..HEAD"
@@ -3214,20 +3367,85 @@ def default_audit_range(project: Path) -> str:
     return "HEAD"
 
 
+def rewrite_safe_range(project: Path, rev_range: str) -> str:
+    """Narrow ``A..B`` to ``B`` when ``A`` no longer exists, and say so.
+
+    A push event hands CI the revision the branch had before the push. When that
+    push *rewrote* history - the sanctioned repair for a commit carrying a
+    personal mailbox - the old revision is gone, ``git log A..B`` exits 128 with
+    "Invalid revision range", and the identity audit dies over a range that can no
+    longer be measured. The new tip can still be audited, so audit it, name the
+    rewrite, and never pretend the unmeasurable span was clean.
+    """
+    if ".." not in rev_range:
+        return rev_range
+    base = rev_range.split("..", 1)[0].strip()
+    if not base or base.startswith("-"):
+        return rev_range
+    if run_git(project, "cat-file", "-e", f"{base}^{{commit}}").returncode == 0:
+        return rev_range
+    print(
+        f"# {base[:12]} is not an ancestor of this clone (history rewrite): "
+        f"auditing the tip only, the span before it is unmeasurable"
+    )
+    tip = rev_range.split("..", 1)[1].strip() or "HEAD"
+    if run_git(project, "rev-parse", "--verify", "--quiet", f"{tip}^").returncode != 0:
+        return tip  # a root commit is its own whole history
+    # ``tip`` alone means "every ancestor of tip", which would re-audit the whole
+    # history the event never covered - one rewrite then turns every old blemish
+    # red at once. The span that can be measured is exactly the new tip.
+    return f"{tip}^..{tip}"
+
+
+def _matches_role_display(name: str, canonical_display: str) -> bool:
+    """A role mailbox may display its role spaced or run together.
+
+    ``role_identity`` yields the spaced form (``Project Manager``), while the team
+    commits with ``git -c user.name=ProjectManager`` - the same canonical role,
+    written without spaces. Accept both; anything else is a different name.
+    """
+    return name.replace(" ", "") == canonical_display.replace(" ", "")
+
+
+def _is_content_free_team_merge(
+    parents: list, name: str, email: str, body: str, canonical: dict
+) -> bool:
+    """A two-parent integration merge with no body adds no content, so it
+    carries no acting role. Single-parent commits are never exempt: they do add
+    content and must say who acted.
+    """
+    if len(parents) < 2 or email not in canonical:
+        return False
+    if not _matches_role_display(name, canonical[email]):
+        return False
+    lines = body.splitlines()
+    if not lines or not _RE_MERGE_SUBJECT.match(lines[0].strip()):
+        return False
+    return not "".join(lines[1:]).strip()
+
+
 def audit_commit_identities(project: Path, rev_range: str, strict_authors: bool = False) -> int:
     """Fail when a commit is not authored and committed by the acting role.
 
     The role that does the work commits it. A forge-created pull-request merge ref
     carries the forge account identity, so it is skipped; its own history is
-    audited by the caller's range. Bot dependency updates are allowed. A public
+    audited by the caller's range. A forge-side *rebase* merge is accepted too: it
+    keeps the author and stamps only its own noreply committer, so the acting role
+    is still the author (see ``_RE_FORGE_COMMITTER_EMAIL``). Bot dependency updates
+    are allowed. A public
     repository also receives outside contributions: unless ``strict_authors`` is
     set, an author outside the team's identity domain is reported as skipped
     rather than failed, while a team-domain author with the wrong role still
     fails.
     """
+    # Name the repository before anything else: the same command in a lane worktree
+    # and in the primary checkout read different histories, so a reader who cannot
+    # see which one was read cannot tell a clean branch from an unaudited one.
+    print(f"# Repository read: {project}")
     if rev_range.startswith("-"):
         print(f"teamwork: invalid revision range {rev_range!r}")
         return 2
+    rev_range = rewrite_safe_range(project, rev_range)
     proc = run_git(
         project, "log", "--format=%H%x1f%an%x1f%ae%x1f%cn%x1f%ce%x1f%P%x1f%B%x1e", rev_range
     )
@@ -3265,19 +3483,42 @@ def audit_commit_identities(project: Path, rev_range: str, strict_authors: bool
                 print(f"- {short} skipped: external contributor {an} <{ae}>")
                 continue
             reasons.append(f"not a role mailbox: {ae}")
-        elif an != expected:
+        elif not _matches_role_display(an, expected):
             reasons.append(f"display name {an!r} does not match role {expected!r}")
-        if ce != ae or cn != an:
+        # A forge-side merge stamps its own noreply committer - but only for a
+        # commit whose author is a canonical role mailbox, so the identity that
+        # matters (the acting role) is still enforced by every check here.
+        forge_committer = expected is not None and _RE_FORGE_COMMITTER_EMAIL.match(ce) is not None
+        # A merge commit lands a peer's reviewed work, so the committer need not be
+        # the author. That is only acceptable when the committer is itself a
+        # canonical role mailbox (the reviewer/CEO who merged): a personal address
+        # stamping someone else's commit is exactly the privacy defect this gate
+        # exists for, so it stays a failure.
+        landing_role = canonical.get(ce) if ce in canonical and (ce != ae or cn != an) else None
+        if (ce != ae or cn != an) and not forge_committer and landing_role is None:
             reasons.append(f"committer {cn} <{ce}> differs from author {an} <{ae}>")
         match = _RE_ACTING_ROLE.search(body)
         if not match:
-            reasons.append("message has no 'Acting role:' line")
-        elif match.group(1) != an:
+            # The structured ``Role:`` trailer carries the same machine-written
+            # fact; accept it, but only when it names the author's own role.
+            match = _RE_ROLE_FIELD.search(body)
+            if match:
+                fallback_role = resolve_role(match.group(1))
+                if not _matches_role_display(an, role_identity(fallback_role)[0]):
+                    reasons.append(f"'Role: {match.group(1)}' does not match author {an!r}")
+                    match = None
+        elif not _matches_role_display(match.group(1), an):
             reasons.append(f"'Acting role: {match.group(1)}' does not match author {an!r}")
+        if not match and not _is_content_free_team_merge(parents, cn, ce, body, canonical):
+            reasons.append("message has no 'Acting role:' line")
         if reasons:
             problems.append((short, reasons))
             for reason in reasons:
                 print(f"- {short} FAIL {an} <{ae}>: {reason}")
+        elif landing_role is not None:
+            print(f"- {short} ok {an} <{ae}> (landed by {landing_role})")
+        elif forge_committer:
+            print(f"- {short} ok {an} <{ae}> (forge committer {ce})")
         else:
             print(f"- {short} ok {an} <{ae}>")
     print(f"# commits: {seen} | problems: {len(problems)}")
@@ -3431,6 +3672,7 @@ def cmd_commit(args) -> int:
                 if (
                     fp.is_file()
                     and fp.stat().st_size > args.lfs_threshold
+                    and is_binary_content(fp)
                     and not lfs_tracked(project, line)
                 ):
                     big.append(f"{line} ({fp.stat().st_size // 1024} KiB)")
@@ -3444,6 +3686,17 @@ def cmd_commit(args) -> int:
                 " --lfs-threshold",
                 2,
             )
+        mismatched = [line for line in staged.splitlines() if lfs_text_mismatch(project, line)]
+        if mismatched:
+            die(
+                "refusing to commit text file(s) that .gitattributes routes into Git "
+                "LFS:\n  "
+                + "\n  ".join(mismatched)
+                + "\n  this file is text but a LFS pattern captures its name; LFS is "
+                "for binaries, and a document in LFS is unreadable without a client."
+                "\n  drop the pattern from .gitattributes, or make the content binary.",
+                2,
+            )
 
     r = subprocess.run(
         ["git", "-C", str(project)] + git_identity_args(role) + ["commit", "-F", "-"],
@@ -3569,6 +3822,262 @@ def roster_for(names: list) -> dict:
     return {"tier": "explicit", "roles": roles, "instances": names, "missing_required": missing}
 
 
+def scaffold_role(root: Path, role: str, staffed: set | None = None, force: bool = False) -> Path:
+    """Role scope: one shared memory set, queue and charter for every instance.
+
+    Idempotent and non-destructive: existing files are never rewritten unless
+    ``force`` names the charter. Called by `init` and by `instance add`, so a role
+    that gains a fifth instance does not gain a second memory file.
+    """
+    role = resolve_role(role)
+    rd = role_dir(root, role)
+    rd.mkdir(parents=True, exist_ok=True)
+    for filename in (F_SHORT, F_LONG, F_MEM_ARCHIVE):
+        p = rd / filename
+        if not p.exists():
+            write_memory(p, [], filename, role)
+    tp = rd / F_TASKS
+    if not tp.exists():
+        write_tasks(tp, [], role)
+    role_file = ROLES_DIR / f"{role}.md"
+    shared_charter = rd / F_ROLE
+    if role_file.exists() and (force or not shared_charter.exists()):
+        body = role_file.read_text(encoding="utf-8").replace(
+            "{references}", str(SKILL_DIR / "references")
+        )
+        folded = charter_reports_line(role, staffed)
+        if folded:
+            body = fold_charter_reports(body, folded)
+        write_lf(shared_charter, body)
+    elif not shared_charter.exists():
+        write_lf(
+            shared_charter,
+            f"# Role: {role}\n\n"
+            f"No bundled charter found for '{role}'. Derive your duties from the\n"
+            f"task packet, report blockers to the CEO, and keep to your lane.\n",
+        )
+    return rd
+
+
+def scaffold_instance(
+    root: Path, name: str, role: str, staffed: set | None = None, force: bool = False
+) -> Path:
+    """Instance scope: private brief, worklog, inbox, artifacts, scratch, reports."""
+    d = agent_dir(root, name)
+    for sub in (DIR_ARTIFACTS, DIR_SCRATCH, DIR_REPORTS):
+        (d / sub).mkdir(parents=True, exist_ok=True)
+    brief = d / F_START
+    if force or not brief.exists():
+        write_lf(brief, start_here(name, role, root, docs_dir(root), staffed=staffed))
+    for extra in (F_WORKLOG, F_INBOX):
+        p = d / extra
+        if p.exists():
+            continue
+        write_lf(
+            p,
+            f"# {extra[:-3]} - {name} ({role})\n\n"
+            f"> Private to this instance. The {role} memory and task queue\n"
+            f"> are shared with every other {role} instance, and only one instance\n"
+            f"> of the role revises that memory at a time (`memory claim {role}`).\n\n"
+            + AGENT_LINKS.format(**link_fields(d / extra, name))
+            + "\n",
+        )
+    migrate_instance_memory(root, name, role)
+    return d
+
+
+def next_instance_name(root: Path, role: str) -> str:
+    """The next free instance name for a role: `role-N`, or `role` when it is alone.
+
+    A bare role name is the role's first instance, so a role that already has one
+    gains `-2` rather than reusing a name or renaming a lane that records already
+    name (`claimed_by`, branches, ledger entries).
+    """
+    role_p = pascal(role)
+    taken = {pascal(i) for i in instances_of(root, role)}
+    if not taken:
+        return role_p
+    n = 2 if role_p in taken else 1
+    while f"{role_p}-{n}" in taken:
+        n += 1
+    return f"{role_p}-{n}"
+
+
+def cmd_instance(args) -> int:
+    """Every role scales: `instance add|list|retire`.
+
+    Roles differ in what they own, not in how many lanes may serve it: any role
+    can run several instances, they share the role's memory and queue, and the
+    memory lease (`memory claim`) keeps exactly one of them revising it.
+    """
+    root = project_root(args)
+    if not role_dir(root, "ceo").parent.is_dir() and not agents_dir(root).is_dir():
+        die("no workspace here: run `teamwork.py init` first")
+    if args.instance_cmd == "list":
+        return _instance_list(root, args.json)
+    if args.instance_cmd == "retire":
+        return _instance_retire(root, args)
+    return _instance_add(root, args)
+
+
+def _instance_add(root: Path, args) -> int:
+    import json
+
+    role = resolve_role(args.role)
+    count = max(int(args.count or 1), 1)
+    names = list_roles(root)
+    if role not in names and names and not args.new_role:
+        die(
+            f"the {role} role has no seat in this team. Staffed roles: {', '.join(names)}.\n"
+            f"  Add it anyway with `--new-role` (it gets the shared memory set and a "
+            f"charter copy like any other role), or fix the spelling."
+        )
+    by = (args.by or "ceo").strip()
+    staffed = set(names) | {role}
+    if args.name and count > 1:
+        die("--name names ONE instance; drop --count or add them one at a time", 2)
+    created = []
+    for _ in range(count):
+        if args.name:
+            if resolve_role(args.name) != role:
+                die(
+                    f"'{args.name}' resolves to the {resolve_role(args.name)} role, "
+                    f"not {role}. An instance name must belong to the role it serves.",
+                    2,
+                )
+            name = pascal(args.name)
+            if agent_dir(root, name).is_dir():
+                die(f"instance '{name}' already exists", 2)
+        else:
+            name = next_instance_name(root, role)
+        scaffold_role(root, role, staffed=staffed)
+        scaffold_instance(root, name, role, staffed=staffed)
+        created.append(name)
+        ledger_append(
+            root,
+            "instance.add",
+            by,
+            name,
+            f"{role} instance {name}; shared memory Roles/{pascal(role)}",
+            "",
+            role,
+        )
+    if args.json:
+        print(json.dumps({"role": role, "created": created}, indent=2))
+        return 0
+    inst = instances_of(root, role)
+    print(f"teamwork: added {len(created)} {role} instance(s): {', '.join(created)}")
+    print(f"#   shared memory (ONE reviser at a time): {role_dir(root, role)}")
+    print(f"#   {role} instances now: {', '.join(inst)}")
+    print(
+        f"#   start one with: teamwork.py load {created[0]} && teamwork.py task next {created[0]}"
+    )
+    print(f"#   the role's memory pen: teamwork.py memory claim {role} --by {created[0]}")
+    if len(inst) > 1:
+        print(
+            f"#   WARNING {len(inst)} {role} instances share one queue and one memory. "
+            "Two of them editing the memory at once is impossible (`memory claim` "
+            "leases it), but each lane still needs its own branch: "
+            f"`branch start --agent {created[0]} --task <T-id>`."
+        )
+    return 0
+
+
+def _instance_list(root: Path, as_json: bool) -> int:
+    import json
+
+    rows = []
+    for role in list_roles(root):
+        claim = read_memory_claim(root, role)
+        rows.append(
+            {
+                "role": role,
+                "instances": instances_of(root, role),
+                "memory_writer": pascal(claim["instance"]) if claim else "",
+                "minutes_left": memory_claim_remaining(claim) if claim else 0,
+                "tasks": len(parse_tasks(task_file(root, role))),
+            }
+        )
+    if as_json:
+        print(json.dumps({"roles": rows}, indent=2))
+        return 0
+    if not rows:
+        print("teamwork: no role in this workspace yet")
+        return 0
+    for row in rows:
+        holder = (
+            f"memory-writer: {row['memory_writer']} ({row['minutes_left']}m)"
+            if row["memory_writer"]
+            else "memory free"
+        )
+        print(
+            f"{row['role']:20s} instances={len(row['instances']):2d} "
+            f"[{', '.join(row['instances']) or '-'}]  tasks={row['tasks']:3d}  {holder}"
+        )
+    return 0
+
+
+def _instance_retire(root: Path, args) -> int:
+    name, role = validate_actor(root, args.name, "instance")
+    d = agent_dir(root, name)
+    if not d.is_dir():
+        hint = (
+            " The bare role name is only an instance when `Agents/<Role>/` exists - "
+            f"this team's {role} lanes are: {', '.join(instances_of(root, role)) or 'none'}."
+        )
+        die(f"no instance directory for '{name}'.{hint}")
+    by = (args.by or "ceo").strip()
+    blockers = _instance_busy_reasons(root, role, name)
+    if blockers and not args.reason:
+        die("--reason is required to retire an instance", 2)
+    if blockers and not args.force:
+        die(
+            f"{name} is not idle: {'; '.join(blockers)}.\n"
+            f"  Reclaim or finish that work, then retire it, or pass "
+            f'`--force "<why>"` so the record says what was abandoned.',
+            2,
+        )
+    shutil.rmtree(d)
+    ledger_append(
+        root,
+        "instance.retire",
+        by,
+        name,
+        (args.reason or "no reason given")
+        + (f" | forced past: {'; '.join(blockers)}" if blockers else "")
+        + f" | {role} memory kept at Roles/{pascal(role)}",
+        "",
+        role,
+    )
+    print(f"teamwork: retired {name}; the {role} memory and queue stay in place")
+    if not instances_of(root, role):
+        print(
+            f"#   WARNING no {role} instance left: that lane owns work nobody can take. "
+            f"Add one with `instance add {role}`."
+        )
+    return 0
+
+
+def _instance_busy_reasons(root: Path, role: str, name: str) -> list:
+    reasons = []
+    mine = pascal(name)
+    for t in parse_tasks(task_file(root, role)):
+        if pascal(t.get("claimed_by") or "") == mine and t.get("status") in (
+            "doing",
+            "selfcheck",
+            "review",
+        ):
+            reasons.append(f"{t['id']} is {t.get('status')} by {t.get('claimed_by')}")
+    claim = read_memory_claim(root, role)
+    if claim and pascal(claim["instance"]) == mine:
+        reasons.append(f"it holds the {role} memory pen ({memory_claim_remaining(claim)} min left)")
+    slots = root / DIR_RUNTIME / DIR_SLOTS
+    if slots.is_dir():
+        for slot in slots.glob(f"*/{safe_component(mine)}.slot"):
+            reasons.append(f"a provider slot is leased ({slot.parent.name})")
+    return reasons
+
+
 def cmd_init(args) -> int:
     root = project_root(args)
     project = project_of(root)
@@ -3659,60 +4168,10 @@ def cmd_init(args) -> int:
     staffed = {resolve_role(n) for n in names}
     for name in names:
         role = resolve_role(name)
-        # role scope: memory + task queue, shared by every instance of the role
-        rd = role_dir(root, role)
-        rd.mkdir(parents=True, exist_ok=True)
-        for filename in (F_SHORT, F_LONG, F_MEM_ARCHIVE):
-            p = rd / filename
-            if not p.exists():
-                write_memory(p, [], filename, role)
-        tp = rd / F_TASKS
-        if not tp.exists():
-            write_tasks(tp, [], role)
+        scaffold_role(root, role, staffed=staffed, force=args.force)
         if role not in roles_seen:
             roles_seen.append(role)
-
-        # instance scope: private charter copy, worklog, inbox, scratch, outputs
-        d = agent_dir(root, name)
-        for sub in (DIR_ARTIFACTS, DIR_SCRATCH, DIR_REPORTS):
-            (d / sub).mkdir(parents=True, exist_ok=True)
-        role_file = ROLES_DIR / f"{role}.md"
-        shared_charter = rd / F_ROLE
-        if role_file.exists() and (args.force or not shared_charter.exists()):
-            body = role_file.read_text(encoding="utf-8").replace(
-                "{references}", str(SKILL_DIR / "references")
-            )
-            folded = charter_reports_line(role, staffed)
-            if folded:
-                body = fold_charter_reports(body, folded)
-            write_lf(shared_charter, body)
-        elif not shared_charter.exists():
-            write_lf(
-                shared_charter,
-                f"# Role: {role}\n\n"
-                f"No bundled charter found for '{role}'. Derive your duties from the\n"
-                f"task packet, report blockers to the CEO, and keep to your lane.\n",
-            )
-        brief = d / F_START
-        if args.force or not brief.exists():
-            write_lf(
-                brief,
-                start_here(
-                    name, role, root, docs_dir(root), staffed={resolve_role(n) for n in names}
-                ),
-            )
-        for extra in (F_WORKLOG, F_INBOX):
-            p = d / extra
-            if not p.exists():
-                write_lf(
-                    p,
-                    f"# {extra[:-3]} - {name} ({role})\n\n"
-                    f"> Private to this instance. The {role} memory and task queue\n"
-                    f"> are shared with every other {role} instance.\n\n"
-                    + AGENT_LINKS.format(**link_fields(d / extra, name))
-                    + "\n",
-                )
-        migrate_instance_memory(root, name, role)
+        scaffold_instance(root, name, role, staffed=staffed, force=args.force)
         created.append(name)
 
     print(f"teamwork: workspace ready at {root}")
@@ -4023,7 +4482,7 @@ def cmd_load(args) -> int:
     d = role_dir(root, role)
     if not d.is_dir() and not agents_dir(root).is_dir():
         die(f"unknown role '{role}' (run init or check `agents`)")
-    consolidate_agent(root, role, dry_run=False, quiet=True)
+    consolidate_agent(root, role, dry_run=False, quiet=True, actor=args.agent, strict=False)
     limit = args.limit or SHORT_CAP
     entries = parse_memory(d / F_SHORT)
     entries.sort(key=lambda e: parse_date(e["last_used"]), reverse=True)
@@ -4035,6 +4494,19 @@ def cmd_load(args) -> int:
         f" ({len(keep)}/{len(entries)} entries)"
     )
     print(f"# shared by: {', '.join(inst) or role}")
+    claim = read_memory_claim(root, role)
+    if claim:
+        print(
+            f"# READ-ONLY right now: {memory_holder_line(claim)}. "
+            f"Remember/touch/forget will be refused until that lease is released "
+            f"(`memory status {role}`); reads and `recall` always work."
+        )
+    else:
+        print(
+            f"# memory is free: `memory claim {role} --by {args.agent} --reason '<what you "
+            f"are about to update>'` holds the pen for a multi-entry update; a single "
+            f"`remember` takes it automatically."
+        )
     print(
         f"# Long-term entries are NOT loaded; query them with:"
         f' teamwork.py recall "<query>" --agent {role}'
@@ -4064,102 +4536,382 @@ def _memory_path(root: Path, agent: str, layer: str) -> tuple:
     return d / filename, filename
 
 
-def cmd_remember(args) -> int:
-    root = project_root(args)
-    path, filename = _memory_path(root, args.agent, args.layer)
-    if not args.text.strip():
-        die("empty memory text")
-    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{resolve_role(args.agent)}.lock"):
-        entries = parse_memory(path)
-        entry = new_entry(
-            args.text,
-            args.key,
-            args.importance,
-            args.tags,
-            args.pin,
-            by=args.by or "",
-            src=args.src or "",
-            rev=args.rev or "",
-        )
-        entries, merged, added = merge_entries(entries, [entry])
-        write_memory(path, entries, filename, args.agent)
-    ledger_append(
-        root,
-        "memory.add" if added else "memory.update",
-        args.by or args.agent,
-        args.key or args.agent,
-        f"{'added' if added else 'updated'} {args.layer} entry: {args.text[:80]}",
-        args.rev,
-    )
-    consolidate_agent(root, args.agent, dry_run=False, quiet=True)
-    print(f"teamwork: remembered {added} new / {merged} merged entry in {path}")
-    return 0
-
+# --------------------------------------------------------------------------- #
+# Role memory: ONE revising instance at a time
+# --------------------------------------------------------------------------- #
+# `Runtime/Locks/role-<Role>.lock` makes a single write atomic, and that is all it
+# does. Two instances of one role can still interleave their edits: A adds entry
+# 1, B consolidates and evicts it, A adds entry 2 against a file it never saw - and
+# the role's memory ends up as a merge nobody reasoned about. The lease below is
+# the missing rule: one instance of the role holds the pen, every other instance of
+# that role is read-only until the pen is released or its lease expires. Several
+# roles revise their own memory in parallel; instances within a role do not.
+#
+# Two ways to hold it, both under the same state file:
+#   * explicit - `memory claim` / `memory release`; held across several commands so
+#     one coherent update lands before a peer looks at the file ("until the memory
+#     for that role is fully updated");
+#   * implicit - one mutating command (`remember`, `forget`, `touch`,
+#     `consolidate`) takes the pen for its own duration and gives it back. Two
+#     peers still serialise instead of interleaving, without a second ceremony.
 
-def cmd_global(args) -> int:
-    root = project_root(args)
-    path = global_dir(root) / F_GLOBAL
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with lock(root / DIR_RUNTIME / DIR_LOCKS / "global.lock"):
-        entries = parse_memory(path)
-        entry = new_entry(args.text, args.key, args.importance, args.tags, args.pin)
-        entries, merged, added = merge_entries(entries, [entry])
-        entries.sort(key=score, reverse=True)
-        pinned = [e for e in entries if e["pinned"]]
-        rest = [e for e in entries if not e["pinned"]]
-        cap = max(LONG_CAP - len(pinned), 0)
-        if len(rest) > cap:
-            archive_path = global_dir(root) / F_GLOBAL_ARCHIVE
-            archived = parse_memory(archive_path)
-            archived, _, _ = merge_entries(archived, rest[cap:])
-            archived.sort(key=score, reverse=True)
-            write_memory(archive_path, archived[:ARCHIVE_CAP], F_GLOBAL_ARCHIVE, "all agents")
-            rest = rest[:cap]
-        write_memory(path, pinned + rest, F_GLOBAL, "all agents")
-    ledger_append(
-        root,
-        "memory.global",
-        "ceo",
-        args.key or "global",
-        f"{added} new / {merged} merged: {args.text[:80]}",
-    )
-    print(f"teamwork: global memory {added} new / {merged} merged ({path})")
-    return 0
 
+def memory_claim_path(root: Path, role: str) -> Path:
+    return root / DIR_RUNTIME / DIR_LOCKS / f"memory-{resolve_role(role)}.claim"
 
-def cmd_recall(args) -> int:
-    root = project_root(args)
-    if args.query:
-        try:
-            pattern = re.compile(args.query, re.IGNORECASE)
-        except re.error as exc:
-            die(
-                f"invalid query pattern {args.query!r}: {exc}. "
-                "Pass a plain text query or a valid regex."
-            )
-    else:
-        pattern = None
-    targets = []  # (owner_label, path, filename)
-    if args.global_ or args.all:
-        for f in sorted(global_dir(root).glob("*.md")):
-            targets.append(("global", f, f.name))
-    if args.all:
-        for name in list_roles(root):
-            for f in (role_dir(root, name) / F_LONG, role_dir(root, name) / F_SHORT):
-                targets.append((name, f, f.name))
-    elif args.agent:
-        role = resolve_role(args.agent)
-        for layer in (
-            ["short"]
-            if args.layer == "short"
-            else ["long"]
-            if args.layer == "long"
-            else ["short", "long"]
-        ):
-            f = role_dir(root, role) / (F_SHORT if layer == "short" else F_LONG)
-            targets.append((role, f, f.name))
-    if not targets:
-        die("nothing to search: pass --agent A, --global, or --all")
+
+def memory_lease_minutes(root: Path) -> int:
+    try:
+        return max(int(_load_settings(root).get("MemoryLeaseMinutes", MEMORY_LEASE_MINUTES)), 1)
+    except (TypeError, ValueError):
+        return MEMORY_LEASE_MINUTES
+
+
+def memory_stall_minutes(root: Path) -> int:
+    """How long a lease is held before the role's peers may call it stalled."""
+    try:
+        return max(int(_load_settings(root).get("MemoryStallMinutes", MEMORY_STALL_MINUTES)), 1)
+    except (TypeError, ValueError):
+        return MEMORY_STALL_MINUTES
+
+
+def memory_claim_age(claim: dict) -> int | None:
+    return claim_age_minutes(claim.get("acquired") or "")
+
+
+def memory_claim_is_slow(root: Path, claim: dict) -> bool:
+    age = memory_claim_age(claim)
+    return age is not None and age >= memory_stall_minutes(root)
+
+
+def memory_arbiter(root: Path, holder_role: str = "") -> tuple:
+    """Who rules on a contested memory lease on THIS roster: (role, skipped).
+
+    The CTO owns engineering standards and the build and lock policy, so a stuck
+    writer is an engineering question. On a roster without a CTO the request folds
+    up the reporting line to the CEO (AGENTS.md: a vacant manager escalates to the
+    CEO), and a party never rules its own lease - a CTO's own memory being contested
+    goes to the CEO.
+    """
+    staffed = set(list_roles(root))
+    chain = [MEMORY_ARBITER_ROLE]
+    while chain[-1] != "ceo" and chain[-1] in ROLE_PARENT:
+        chain.append(ROLE_PARENT[chain[-1]] or "ceo")
+    held_by = resolve_role(holder_role) if holder_role else ""
+    skipped = []
+    for role in chain:
+        if role == held_by:
+            skipped.append(role)
+            continue
+        if role in staffed:
+            return role, skipped
+        skipped.append(role)
+    return "", skipped
+
+
+def read_memory_claim(root: Path, role: str) -> dict:
+    """The live revision lease for this role's shared memory, or {} when free."""
+    import json
+
+    path = memory_claim_path(root, role)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict) or not data.get("instance"):
+        return {}
+    try:
+        expires = float(data.get("expires_ts") or 0)
+    except (TypeError, ValueError):
+        return {}
+    if expires <= time.time():
+        return {}
+    return data
+
+
+def memory_claim_remaining(claim: dict) -> int:
+    try:
+        return max(int(round((float(claim.get("expires_ts") or 0) - time.time()) / 60.0)), 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def memory_holder_line(claim: dict) -> str:
+    role = claim.get("role") or resolve_role(claim.get("instance", ""))
+    return (
+        f"{pascal(claim['instance'])} is revising the {role} memory "
+        f"({memory_claim_remaining(claim)} min left on its lease, "
+        f"since {claim.get('acquired') or '-'}: {claim.get('reason') or 'no reason given'})"
+    )
+
+
+def _write_memory_claim(root: Path, claim: dict) -> dict:
+    import json
+
+    path = memory_claim_path(root, claim["role"])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write(path, json.dumps(claim, indent=2, sort_keys=True) + "\n")
+    return claim
+
+
+def _clear_memory_claim(root: Path, role: str, token: str) -> bool:
+    """Remove the lease only if this process still owns it."""
+    path = memory_claim_path(root, role)
+    try:
+        import json
+
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(data, dict) or data.get("token") != token:
+        return False
+    try:
+        path.unlink()
+    except OSError:
+        return False
+    return True
+
+
+def memory_actor(root: Path, role: str, actor: str = "", require_instance: bool = False) -> str:
+    """The instance acting on a role's memory, validated against that role.
+
+    A bare role name is accepted (it means the role's own pool) unless the caller
+    needs one accountable instance - `memory claim` does, because the lease names
+    who holds the pen. The CEO may hold it too: the shared tree is the CEO's, and a
+    seat that holds the pen still excludes every peer.
+    """
+    role = resolve_role(role)
+    raw = (actor or "").strip()
+    if not raw:
+        return pascal(role)
+    resolved = resolve_role(raw)
+    if resolved != role:
+        if resolved == "ceo":
+            return pascal(raw)
+        die(
+            f"'{raw}' belongs to the {resolved} role, not {role}. A role's shared "
+            f"memory is revised by its own instances (or the CEO), so a lane cannot "
+            f"rewrite a peer role's memory."
+        )
+    inst = pascal(raw)
+    insts = instances_of(root, role)
+    names = {pascal(i) for i in insts}
+    # A name that IS an instance is never ambiguous, even when it equals the role's
+    # own name (`memory claim cto --by CTO` with CTO and CTO-2 both staffed). Only a
+    # role name with no such directory means "the role's pool", and a lease must not
+    # name a pool.
+    if inst == pascal(role) and require_instance and inst not in names:
+        if len(insts) > 1:
+            die(
+                f"name the {role} instance holding the pen: '{raw}' is the role, and it "
+                f"has {', '.join(insts)}. Only one instance of a role revises its shared "
+                f"memory at a time, so the lease must name one of them "
+                f"(`--by {insts[-1]}`)."
+            )
+        return pascal(insts[0]) if insts else inst
+    known = names
+    if known and inst not in known and inst != pascal(role):
+        die(
+            f"unknown {role} instance '{raw}'. Known: {', '.join(sorted(known))}. "
+            f"Add one with `teamwork.py instance add {role}`."
+        )
+    return inst
+
+
+@contextlib.contextmanager
+def memory_session(
+    root: Path,
+    role: str,
+    actor: str = "",
+    reason: str = "",
+    strict: bool = True,
+    minutes: int | None = None,
+):
+    """Hold the role's memory pen for the body, then give it back.
+
+    Yields the live claim, or ``None`` when ``strict`` is false and a peer holds an
+    explicit lease - a read path (`load` consolidating in the background) degrades
+    to "skip maintenance" instead of failing the lane that only wanted to read.
+    """
+    role = resolve_role(role)
+    inst = memory_actor(root, role, actor)
+    lock_path = root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"
+    ttl = max(int(minutes or memory_lease_minutes(root)), 1)
+
+    def peer_holds() -> dict:
+        held = read_memory_claim(root, role)
+        if held and held.get("explicit") and pascal(held["instance"]) != inst:
+            return held
+        return {}
+
+    blocked = peer_holds()
+    if blocked:
+        if strict:
+            die(
+                f"{memory_holder_line(blocked)}. Only one instance of the {role} role "
+                f"revises its shared memory at a time. Read it (`recall`) and retry "
+                f"when the lease is released, or take the pen deliberately: "
+                f'`memory claim {role} --by {inst} --force "<why>"`.',
+                2,
+            )
+        yield None
+        return
+
+    with lock(lock_path):
+        blocked = peer_holds()
+        if blocked:
+            if not strict:
+                yield None
+                return
+            die(
+                f"{memory_holder_line(blocked)}. Only one instance of the {role} role "
+                f"revises its shared memory at a time.",
+                2,
+            )
+        held = read_memory_claim(root, role)
+        explicit = bool(held.get("explicit")) and pascal(held["instance"]) == inst
+        # Joining my own lease keeps what the arbiter and the peers put on it:
+        # a pending contest must not vanish because the holder wrote one more
+        # entry, and an arbiter's ruling must stay on the record.
+        claim = dict(held) if explicit else {}
+        claim.update(
+            {
+                "role": role,
+                "instance": inst,
+                "token": f"{os.getpid()}.{time.time():.6f}",
+                "acquired": (held.get("acquired") if explicit else "")
+                or datetime.datetime.now().isoformat(timespec="seconds"),
+                "expires_ts": time.time() + ttl * 60.0,
+                "minutes": ttl,
+                "explicit": explicit,
+                "reason": (held.get("reason") if explicit else "") or reason or "memory update",
+            }
+        )
+        _write_memory_claim(root, claim)
+        try:
+            yield claim
+        finally:
+            # An explicit lease outlives the command that created it; it is the
+            # whole point of `memory claim`. An implicit one dies with the write.
+            if not claim["explicit"]:
+                _clear_memory_claim(root, role, claim["token"])
+
+
+def _role_memory_paths(root: Path, role: str) -> tuple:
+    d = role_dir(root, role)
+    return d, d / F_SHORT, d / F_LONG, d / F_MEM_ARCHIVE
+
+
+def cmd_remember(args) -> int:
+    root = project_root(args)
+    path, filename = _memory_path(root, args.agent, args.layer)
+    if not args.text.strip():
+        die("empty memory text")
+    role = resolve_role(args.agent)
+    with memory_session(root, role, args.by or args.agent, reason=f"remember {args.key or 'note'}"):
+        entries = parse_memory(path)
+        entry = new_entry(
+            args.text,
+            args.key,
+            args.importance,
+            args.tags,
+            args.pin,
+            by=args.by or "",
+            src=args.src or "",
+            rev=args.rev or "",
+        )
+        entries, merged, added = merge_entries(entries, [entry])
+        write_memory(path, entries, filename, args.agent)
+        ledger_append(
+            root,
+            "memory.add" if added else "memory.update",
+            args.by or args.agent,
+            args.key or args.agent,
+            f"{'added' if added else 'updated'} {args.layer} entry: {args.text[:80]}",
+            args.rev,
+        )
+        d, short_path, long_path, arch_path = _role_memory_paths(root, role)
+        _consolidate_locked(
+            root, role, role, d, short_path, long_path, arch_path, dry_run=False, quiet=True
+        )
+    print(f"teamwork: remembered {added} new / {merged} merged entry in {path}")
+    return 0
+
+
+def cmd_global(args) -> int:
+    root = project_root(args)
+    path = global_dir(root) / F_GLOBAL
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / "global.lock"):
+        entries = parse_memory(path)
+        entry = new_entry(
+            args.text,
+            args.key,
+            args.importance,
+            args.tags,
+            args.pin,
+            by=args.by or "",
+            src=args.src or "",
+            rev=args.rev or "",
+        )
+        entries, merged, added = merge_entries(entries, [entry])
+        entries.sort(key=score, reverse=True)
+        pinned = [e for e in entries if e["pinned"]]
+        rest = [e for e in entries if not e["pinned"]]
+        cap = max(LONG_CAP - len(pinned), 0)
+        if len(rest) > cap:
+            archive_path = global_dir(root) / F_GLOBAL_ARCHIVE
+            archived = parse_memory(archive_path)
+            archived, _, _ = merge_entries(archived, rest[cap:])
+            archived.sort(key=score, reverse=True)
+            write_memory(archive_path, archived[:ARCHIVE_CAP], F_GLOBAL_ARCHIVE, "all agents")
+            rest = rest[:cap]
+        write_memory(path, pinned + rest, F_GLOBAL, "all agents")
+    ledger_append(
+        root,
+        "memory.global",
+        args.by or "ceo",
+        args.key or "global",
+        f"{added} new / {merged} merged: {args.text[:80]}",
+        args.rev,
+    )
+    print(f"teamwork: global memory {added} new / {merged} merged ({path})")
+    return 0
+
+
+def cmd_recall(args) -> int:
+    root = project_root(args)
+    if args.query:
+        try:
+            pattern = re.compile(args.query, re.IGNORECASE)
+        except re.error as exc:
+            die(
+                f"invalid query pattern {args.query!r}: {exc}. "
+                "Pass a plain text query or a valid regex."
+            )
+    else:
+        pattern = None
+    targets = []  # (owner_label, path, filename)
+    if args.global_ or args.all:
+        for f in sorted(global_dir(root).glob("*.md")):
+            targets.append(("global", f, f.name))
+    if args.all:
+        for name in list_roles(root):
+            for f in (role_dir(root, name) / F_LONG, role_dir(root, name) / F_SHORT):
+                targets.append((name, f, f.name))
+    elif args.agent:
+        role = resolve_role(args.agent)
+        for layer in (
+            ["short"]
+            if args.layer == "short"
+            else ["long"]
+            if args.layer == "long"
+            else ["short", "long"]
+        ):
+            f = role_dir(root, role) / (F_SHORT if layer == "short" else F_LONG)
+            targets.append((role, f, f.name))
+    if not targets:
+        die("nothing to search: pass --agent A, --global, or --all")
 
     total = 0
     for owner, path, filename in targets:
@@ -4206,7 +4958,9 @@ def _find_entry(entries: list, handle: str):
 def cmd_touch(args) -> int:
     root = project_root(args)
     path, filename = _memory_path(root, args.agent, args.layer)
-    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{resolve_role(args.agent)}.lock"):
+    role = resolve_role(args.agent)
+    actor = getattr(args, "by", "") or args.agent
+    with memory_session(root, role, actor, reason=f"touch {args.handle}"):
         entries = parse_memory(path)
         idx = _find_entry(entries, args.handle)
         if idx is None:
@@ -4214,49 +4968,427 @@ def cmd_touch(args) -> int:
         entries[idx]["uses"] += 1
         entries[idx]["last_used"] = today_iso()
         write_memory(path, entries, filename, args.agent)
+        ledger_append(
+            root,
+            "memory.touch",
+            actor,
+            entries[idx]["key"] or args.handle,
+            f"uses={entries[idx]['uses']}",
+        )
+    print(f"teamwork: touched {entries[idx]['key'] or args.handle} (uses={entries[idx]['uses']})")
+    return 0
+
+
+def cmd_forget(args) -> int:
+    root = project_root(args)
+    path, filename = _memory_path(root, args.agent, args.layer)
+    role = resolve_role(args.agent)
+    actor = getattr(args, "by", "") or args.agent
+    with memory_session(root, role, actor, reason=f"forget {args.handle}"):
+        entries = parse_memory(path)
+        idx = _find_entry(entries, args.handle)
+        if idx is None:
+            die(f"no entry '{args.handle}' in {path}")
+        removed = entries.pop(idx)
+        write_memory(path, entries, filename, args.agent)
+        ledger_append(
+            root,
+            "memory.forget",
+            actor,
+            removed["key"] or args.handle,
+            f"removed: {(removed.get('body') or '')[:80]}",
+        )
+    print(f"teamwork: forgot {removed['key'] or args.handle}")
+    return 0
+
+
+def cmd_memory(args) -> int:
+    """`memory claim|release|renew|contest|extend|revoke|status`.
+
+    Who may revise a role's memory, who may call a long update stalled, and who
+    rules on it.
+    """
+    root = project_root(args)
+    sub = args.memory_cmd
+    if sub == "status":
+        return _memory_status(root, getattr(args, "agent", "") or "", args.json)
+    role = resolve_role(args.agent)
+    if not role_dir(root, role).is_dir() and not agents_dir(root).is_dir():
+        die("no workspace here: run `teamwork.py init` first")
+    if sub == "claim":
+        actor = memory_actor(root, role, args.by, require_instance=True)
+        return _memory_claim(root, role, actor, args.ttl, args.reason, args.force)
+    if sub == "contest":
+        actor = memory_actor(root, role, args.by, require_instance=True)
+        return _memory_contest(root, role, actor, args.reason)
+    if sub in ("extend", "revoke"):
+        # The arbiter is deliberately ANOTHER role (the CTO, folded up to the CEO),
+        # so this path bypasses `memory_actor`: a peer role may not write the
+        # memory, but it may rule on who is allowed to.
+        if not (args.by or "").strip():
+            die(f"--by is required for `memory {sub}`: name the arbiter ruling", 2)
+        actor, _actor_role = validate_actor(root, args.by, "arbiter")
+        return _memory_arbitrate(
+            root, role, actor, sub, getattr(args, "ttl", 0), getattr(args, "reason", "")
+        )
+    actor = memory_actor(root, role, args.by)
+    if sub == "renew":
+        return _memory_renew(root, role, actor, args.ttl)
+    if sub == "release":
+        return _memory_release(root, role, actor, args.force)
+    die(f"unknown memory subcommand '{sub}'")
+
+
+def _memory_contest(root: Path, role: str, actor: str, reason: str) -> int:
+    """A peer of the role asks the arbiter to rule on a lease that is running long."""
+    if not reason.strip():
+        die("--reason is required: what makes this update look stalled?", 2)
+    task_id = ""
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"):
+        held = read_memory_claim(root, role)
+        if not held:
+            print(
+                f"teamwork: no live lease on the {role} memory - nothing to contest. "
+                f"`memory status {role}` shows the truth."
+            )
+            return 0
+        if pascal(held["instance"]) == actor:
+            die(
+                f"{actor} holds the {role} memory pen; a holder does not contest its own "
+                f"lease. Release it (`memory release {role} --by {actor}`) or finish the "
+                f"update.",
+                2,
+            )
+        age = memory_claim_age(held)
+        arbiter, _skipped = memory_arbiter(root, role)
+        if not arbiter:
+            die(
+                "no seat on this roster may rule on that lease (the arbiter and every "
+                "manager above it are the holder's own role). Open a dispute instead: "
+                f"`dispute open --by {actor} --against {held['instance']} --topic "
+                f"'stalled {role} memory lease' --evidence '<age, task, lease>'`.",
+                2,
+            )
+        contests = [c for c in (held.get("contests") or []) if isinstance(c, dict)]
+        contests.append(
+            {
+                "by": actor,
+                "at": datetime.datetime.now().isoformat(timespec="seconds"),
+                "reason": reason.strip(),
+                "age_minutes": age,
+            }
+        )
+        held["contests"] = contests
+        _write_memory_claim(root, held)
+    title = f"Rule on the {role} memory lease held by {pascal(held['instance'])}"
+    body = (
+        f"{actor} contests the {role} memory lease.\n\n"
+        f"- holder: {pascal(held['instance'])}\n"
+        f"- held since: {held.get('acquired') or '-'} ({age if age is not None else '?'} min)\n"
+        f"- lease left: {memory_claim_remaining(held)} min (of {held.get('minutes')})\n"
+        f"- reason given by the holder: {held.get('reason') or '-'}\n"
+        f"- why it looks stalled: {reason.strip()}\n\n"
+        f"Rule with one of:\n"
+        f"- `memory extend {role} --by <you> --ttl 30 --reason '<why more time is fair>'`\n"
+        f"- `memory revoke {role} --by <you> --reason '<why the pen is removed>'`"
+    )
+    task_id = _file_arbiter_task(root, arbiter, title, body, actor, role)
+    ledger_append(
+        root,
+        "memory.contest",
+        actor,
+        role,
+        f"contested {pascal(held['instance'])}'s lease ({age if age is not None else '?'} min)"
+        f" -> {arbiter}{' ' + task_id if task_id else ''}: {reason.strip()[:120]}",
+        "",
+        role,
+    )
+    who = ROLE_DISPLAY.get(arbiter, pascal(arbiter))
+    print(
+        f"teamwork: contest recorded - {pascal(held['instance'])} has held the {role} "
+        f"memory pen for {age if age is not None else '?'} min."
+    )
+    print(f"#   arbiter: {who}" + (f", task {task_id} on its queue" if task_id else ""))
+    print(
+        f"#   {who} rules: `memory extend {role} --by {who} --ttl N` or `memory revoke {role} --by {who} --reason '<why>'`"
+    )
+    return 0
+
+
+def _memory_arbitrate(root: Path, role: str, actor: str, action: str, ttl: int, reason: str) -> int:
+    """`extend` (more time for this holder) or `revoke` (free the role now)."""
+    arbiter, skipped = memory_arbiter(root, role)
+    actor_role = resolve_role(actor)
+    if not arbiter or actor_role not in (arbiter, "ceo"):
+        expected = ROLE_DISPLAY.get(arbiter, pascal(arbiter)) if arbiter else "no seat"
+        folded = f" ({', '.join(skipped)} unstaffed or a party)" if skipped else ""
+        die(
+            f"only the {expected}{folded} rules on the {role} memory lease: the CTO "
+            f"owns engineering standards and the lock policy, and a peer cannot "
+            f"extend or remove another instance's lease. Contest it first: "
+            f"`memory contest {role} --by <you> --reason '<why>'`.",
+            2,
+        )
+    if not reason.strip():
+        die(f"--reason is required for `memory {action}`: the ruling is evidence", 2)
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"):
+        held = read_memory_claim(root, role)
+        if not held:
+            print(
+                f"teamwork: no live lease on the {role} memory - it has already "
+                f"expired or been released; nothing to {action}."
+            )
+            return 0
+        holder = pascal(held["instance"])
+        if action == "extend":
+            minutes = max(int(ttl or held.get("minutes") or memory_lease_minutes(root)), 1)
+            held["expires_ts"] = time.time() + minutes * 60.0
+            held["minutes"] = minutes
+            held["arbitrated_by"] = actor
+            held["arbitrated_at"] = datetime.datetime.now().isoformat(timespec="seconds")
+            held["contests"] = []
+            _write_memory_claim(root, held)
+            detail = (
+                f"extended {holder}'s lease by {minutes} min (contests answered): "
+                f"{reason.strip()[:120]}"
+            )
+        else:
+            _clear_memory_claim(root, role, held["token"])
+            detail = f"revoked {holder}'s lease, {role} memory free: {reason.strip()[:120]}"
+    ledger_append(
+        root,
+        "memory.grant" if action == "extend" else "memory.revoke",
+        actor,
+        role,
+        detail + (f" | skipped from the arbiter chain: {', '.join(skipped)}" if skipped else ""),
+        "",
+        role,
+    )
+    if action == "extend":
+        print(
+            f"teamwork: {holder} keeps the {role} memory pen for {minutes} more min "
+            f"(ruled by {actor})"
+        )
+    else:
+        print(f"teamwork: {holder}'s lease on the {role} memory is revoked; the role is free")
+    return 0
+
+
+def _file_arbiter_task(root: Path, arbiter: str, title: str, body: str, by: str, role: str) -> str:
+    """Put the request on the arbiter's queue, once, without duplicating an open one."""
+    if not instances_of(root, arbiter):
+        return ""
+    path = task_file(root, arbiter)
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{arbiter}.lock"):
+        tasks = parse_tasks(path)
+        for existing in tasks:
+            if existing["title"].strip().lower() == title.strip().lower() and existing[
+                "status"
+            ] not in ("done", "dropped"):
+                return existing["id"]
+        t = new_task(
+            title,
+            "P0",
+            tags="memory-lease,arbitration",
+            body=body,
+            review="na",
+        )
+        t["area"] = "memory-lease"
+        t["claimed_by"] = ""
+        tasks.append(t)
+        write_tasks(path, tasks, arbiter)
+        task_id = tasks[-1]["id"]
+    ledger_append(
+        root,
+        "task.add",
+        by,
+        task_id,
+        f"arbitration request on the {role} memory lease -> {arbiter}",
+        "",
+        arbiter,
+    )
+    return task_id
+
+
+def _memory_claim(root: Path, role: str, actor: str, ttl: int, reason: str, force: str) -> int:
+    minutes = max(int(ttl or memory_lease_minutes(root)), 1)
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"):
+        held = read_memory_claim(root, role)
+        if held and pascal(held["instance"]) != actor:
+            if not force:
+                die(
+                    f"{memory_holder_line(held)}. Only one instance of the {role} role "
+                    f"revises its shared memory at a time. Wait for the release "
+                    f"(`memory status {role}`), or take the pen deliberately with "
+                    f'`--force "<why>"`.',
+                    2,
+                )
+            _clear_memory_claim(root, role, held["token"])
+            ledger_append(
+                root,
+                "memory.claim.force",
+                actor,
+                role,
+                f"took the pen from {pascal(held['instance'])}: {force}",
+                "",
+                role,
+            )
+        claim = {
+            "role": role,
+            "instance": actor,
+            "token": f"{os.getpid()}.{time.time():.6f}",
+            "acquired": datetime.datetime.now().isoformat(timespec="seconds"),
+            "expires_ts": time.time() + minutes * 60.0,
+            "minutes": minutes,
+            "explicit": True,
+            "reason": reason or "memory update",
+        }
+        _write_memory_claim(root, claim)
     ledger_append(
         root,
-        "memory.touch",
-        args.agent,
-        entries[idx]["key"] or args.handle,
-        f"uses={entries[idx]['uses']}",
+        "memory.claim",
+        actor,
+        role,
+        f"explicit {minutes}-minute lease: {claim['reason']}",
+        "",
+        role,
+    )
+    print(
+        f"teamwork: {actor} now revises the {role} memory ({minutes} min lease, "
+        f"expires in {memory_claim_remaining(claim)} min).\n"
+        f"#   every other {role} instance is read-only until "
+        f"`memory release {role} --by {actor}` or the lease expires.\n"
+        f"#   renew with `memory renew {role} --by {actor}` if the update runs long."
     )
-    print(f"teamwork: touched {entries[idx]['key'] or args.handle} (uses={entries[idx]['uses']})")
     return 0
 
 
-def cmd_forget(args) -> int:
-    root = project_root(args)
-    path, filename = _memory_path(root, args.agent, args.layer)
-    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{resolve_role(args.agent)}.lock"):
-        entries = parse_memory(path)
-        idx = _find_entry(entries, args.handle)
-        if idx is None:
-            die(f"no entry '{args.handle}' in {path}")
-        removed = entries.pop(idx)
-        write_memory(path, entries, filename, args.agent)
+def _memory_renew(root: Path, role: str, actor: str, ttl: int) -> int:
+    minutes = max(int(ttl or memory_lease_minutes(root)), 1)
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"):
+        held = read_memory_claim(root, role)
+        if not held:
+            die(
+                f"no live lease on the {role} memory: nothing to renew. Take it with "
+                f"`memory claim {role} --by {actor}`.",
+                2,
+            )
+        if pascal(held["instance"]) != actor:
+            die(
+                f"{memory_holder_line(held)}. Only the holder renews it.",
+                2,
+            )
+        held["expires_ts"] = time.time() + minutes * 60.0
+        held["minutes"] = minutes
+        held["explicit"] = True
+        _write_memory_claim(root, held)
+    ledger_append(root, "memory.renew", actor, role, f"lease extended by {minutes} min", "", role)
+    print(f"teamwork: {actor} holds the {role} memory pen for another {minutes} min")
+    return 0
+
+
+def _memory_release(root: Path, role: str, actor: str, force: str) -> int:
+    with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"):
+        held = read_memory_claim(root, role)
+        if not held:
+            print(f"teamwork: nothing to release - no instance is revising the {role} memory")
+            return 0
+        holder = pascal(held["instance"])
+        if holder != actor and not force:
+            die(
+                f"{memory_holder_line(held)}. Only the holder releases the pen; "
+                f'take it over deliberately with `--force "<why>"` if that lane is gone.',
+                2,
+            )
+        _clear_memory_claim(root, role, held["token"])
     ledger_append(
         root,
-        "memory.forget",
-        args.agent,
-        removed["key"] or args.handle,
-        f"removed: {(removed.get('body') or '')[:80]}",
+        "memory.release",
+        actor,
+        role,
+        f"released the pen held by {holder}" + (f" (forced: {force})" if force else ""),
+        "",
+        role,
     )
-    print(f"teamwork: forgot {removed['key'] or args.handle}")
+    print(f"teamwork: the {role} memory is free; any {role} instance may revise it now")
+    return 0
+
+
+def _memory_status(root: Path, agent: str, as_json: bool) -> int:
+    import json
+
+    roles = [resolve_role(agent)] if agent else list_roles(root)
+    if not roles:
+        print("teamwork: no workspace here (run `teamwork.py init`)")
+        return 0
+    rows = []
+    for role in roles:
+        claim = read_memory_claim(root, role)
+        age = memory_claim_age(claim) if claim else None
+        contests = (
+            [c for c in (claim.get("contests") or []) if isinstance(c, dict)] if claim else []
+        )
+        rows.append(
+            {
+                "role": role,
+                "instances": instances_of(root, role),
+                "holder": pascal(claim["instance"]) if claim else "",
+                "minutes_left": memory_claim_remaining(claim) if claim else 0,
+                "held_minutes": age if age is not None else 0,
+                "since": claim.get("acquired", "") if claim else "",
+                "reason": claim.get("reason", "") if claim else "",
+                "explicit": bool(claim.get("explicit")) if claim else False,
+                "slow": bool(claim) and memory_claim_is_slow(root, claim),
+                "contests": contests,
+                "arbiter": memory_arbiter(root, role)[0] if contests else "",
+            }
+        )
+    if as_json:
+        print(json.dumps({"roles": rows, "stall_minutes": memory_stall_minutes(root)}, indent=2))
+        return 0
+    print(f"# who may revise each role's shared memory now ({len(rows)} role(s))")
+    print(f"# a lease held longer than {memory_stall_minutes(root)} min is contestable")
+    for row in rows:
+        if not row["holder"]:
+            print(f"- {row['role']:18s} free (instances: {', '.join(row['instances']) or '-'})")
+            continue
+        flags = []
+        if row["slow"]:
+            flags.append("SLOW")
+        if row["contests"]:
+            flags.append(f"CONTESTED by {row['contests'][-1].get('by', '?')}")
+        print(
+            f"- {row['role']:18s} revising: {row['holder']:18s} "
+            f"{row['minutes_left']:3d} min left, held {row['held_minutes']:3d} min, "
+            f"since {row['since']}: {row['reason']}" + (f"  [{' / '.join(flags)}]" if flags else "")
+        )
+        if row["contests"]:
+            last = row["contests"][-1]
+            print(
+                f"    contest: {last.get('by', '?')} at {last.get('at', '?')}: "
+                f"{last.get('reason', '')[:120]} -> arbiter {row['arbiter'] or 'none'}"
+            )
     return 0
 
 
-def consolidate_agent(root: Path, agent: str, dry_run: bool = False, quiet: bool = False) -> dict:
+def consolidate_agent(
+    root: Path,
+    agent: str,
+    dry_run: bool = False,
+    quiet: bool = False,
+    actor: str = "",
+    strict: bool = True,
+) -> dict:
     role = resolve_role(agent)
     agent = role
-    d = role_dir(root, role)
-    short_path = d / F_SHORT
-    long_path = d / F_LONG
-    arch_path = d / F_MEM_ARCHIVE
-
-    lock_path = root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"
-    ctx = contextlib.nullcontext() if dry_run else lock(lock_path)
-    with ctx:
+    d, short_path, long_path, arch_path = _role_memory_paths(root, role)
+    if dry_run:
+        return _consolidate_locked(
+            root, role, agent, d, short_path, long_path, arch_path, dry_run, quiet
+        )
+    with memory_session(root, role, actor or agent, reason="consolidate", strict=strict) as claim:
+        if claim is None:
+            return {"agent": agent, "skipped": "another instance is revising this memory"}
         return _consolidate_locked(
             root, role, agent, d, short_path, long_path, arch_path, dry_run, quiet
         )
@@ -4376,8 +5508,9 @@ def cmd_consolidate(args) -> int:
     names = list_roles(root) if (args.all or not args.agent) else [resolve_role(args.agent)]
     if not names:
         die("no agents in this workspace")
+    actor = getattr(args, "by", "") or ""
     for name in names:
-        consolidate_agent(root, name, dry_run=args.dry_run)
+        consolidate_agent(root, name, dry_run=args.dry_run, actor=actor)
     return 0
 
 
@@ -4422,12 +5555,18 @@ def cmd_agents(args) -> int:
         return 0
     for role in roles:
         inst = instances_of(root, role)
+        claim = read_memory_claim(root, role)
+        writer = (
+            f"pen={pascal(claim['instance'])}({memory_claim_remaining(claim)}m)"
+            if claim
+            else "pen=free"
+        )
         print(
             f"{role:20s} instances={len(inst):2d} "
             f"[{', '.join(inst) if inst else '-'}]  "
             f"mem={len(parse_memory(role_dir(root, role) / F_SHORT))}"
             f"/{len(parse_memory(role_dir(root, role) / F_LONG))} "
-            f"tasks={len(parse_tasks(task_file(root, role)))}"
+            f"tasks={len(parse_tasks(task_file(root, role)))} {writer}"
         )
     return 0
 
@@ -4828,6 +5967,7 @@ def cmd_task_add(args) -> int:
             args.body or "",
             args.evidence,
             "na" if args.no_review else "required",
+            getattr(args, "review_profile", ""),
         )
         if args.claimed_by:
             t["claimed_by"] = check_claimant(root, args.claimed_by, "claim", role)
@@ -5077,13 +6217,30 @@ def cmd_task_reclaim(args) -> int:
             die(f"no task '{args.handle}' for {role}")
         t = tasks[idx]
         previous = t.get("claimed_by") or "-"
+        # A live lease is the one honest signal that the owner is working, not
+        # silent. Denying it turns a takeover into a turf war: two lanes undoing
+        # each other's work while both are alive.
+        if t.get("claimed_by") and pascal(t["claimed_by"]) != pascal(actor):
+            reap_slots(root)
+            provider = find_slot_provider(root, t["claimed_by"])
+            if provider and not args.force:
+                die(
+                    f"refusing to reclaim {role}/{t['id']} from {t['claimed_by']}: "
+                    f"that lane still holds a live {provider} slot, so it is working, "
+                    "not silent. Coordinate with it; if you have confirmed the lane "
+                    "is dead, repeat with --force <reason>.",
+                    2,
+                )
+            if provider:
+                args.force = require_reason(args.force, "reclaiming from a live lane")
         t["status"] = "todo"
         t["claimed_by"] = ""
         t["branch"] = t.get("branch") or ""
         t["updated"] = today_iso()
         prev_note = t.get("findings", "")
+        forced_note = f" (forced: {args.force})" if args.force else ""
         t["findings"] = (
-            prev_note + f" | reclaimed from {previous} by {actor}: {args.reason}"
+            prev_note + f" | reclaimed from {previous} by {actor}{forced_note}: {args.reason}"
         ).strip(" |")
         write_tasks(path, tasks, role)
     ledger_append(
@@ -5233,9 +6390,9 @@ def find_slot_provider(root: Path, agent: str) -> str:
     base = root / DIR_RUNTIME / DIR_SLOTS
     if not base.is_dir():
         return ""
-    wanted = safe_component(agent)
+    wanted = {safe_component(agent).lower(), safe_component(pascal(agent)).lower()}
     for prov in sorted(p.name for p in base.iterdir() if p.is_dir()):
-        if wanted in used_slots(root, prov):
+        if any(name.lower() in wanted for name in used_slots(root, prov)):
             return prov
     return ""
 
@@ -5398,7 +6555,157 @@ def claim_age_minutes(value: str) -> int | None:
     return max(int((datetime.datetime.now() - taken).total_seconds() // 60), 0)
 
 
-def review_claim_state(t: dict) -> tuple:
+# Review throughput: the queue, not the depth, is the limit.
+def review_lease_minutes(root: Path) -> int:
+    """A review claim is a short work lease; Settings may override the default."""
+    try:
+        return max(int(_load_settings(root).get("ReviewLeaseMinutes", REVIEW_LEASE_MINUTES)), 1)
+    except (TypeError, ValueError):
+        return REVIEW_LEASE_MINUTES
+
+
+PROSE_REVIEW_PREFIXES = ("docs/", "assets/", "references/")
+PROSE_REVIEW_FILES = (
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "CITATION.cff",
+    "LICENSE",
+    "AGENTS.md",
+    "mkdocs.yml",
+)
+DEEP_REVIEW_TAGS = {"security", "migration", "auth", "crypto", "release", "ci", "infra", "data"}
+DEEP_REVIEW_PREFIXES = (".github/workflows/", ".github/actions/", "migrations/")
+DEEP_REVIEW_MARKERS = ("security", "auth", "crypto", "migration", "release")
+
+
+def _is_prose_review_path(path: str) -> bool:
+    return path in PROSE_REVIEW_FILES or path.startswith(PROSE_REVIEW_PREFIXES)
+
+
+def _is_deep_review_path(path: str) -> bool:
+    low = path.lower()
+    return path.startswith(DEEP_REVIEW_PREFIXES) or any(
+        marker in low for marker in DEEP_REVIEW_MARKERS
+    )
+
+
+def review_profile_for(root: Path, role: str, task: dict) -> tuple:
+    """(profile, reason): fast for prose-only, deep for security/runtime, else standard."""
+    explicit = (task.get("review_profile") or "").strip().lower()
+    if explicit in ("fast", "standard", "deep"):
+        return explicit, "explicitly set"
+    tags = {t.strip().lower() for t in (task.get("tags") or "").split(",") if t.strip()}
+    deep_tags = sorted(tags & DEEP_REVIEW_TAGS)
+    if deep_tags:
+        return "deep", "tag(s): " + ", ".join(deep_tags)
+    area = (task.get("area") or "").lower()
+    if any(marker in area for marker in ("security", "migration", "auth", "release", "ci")):
+        return "deep", f"area: {area}"
+    branch = (task.get("branch") or "").strip()
+    project = project_of(root)
+    if branch and is_git_repo(project) and branch_exists(project, branch):
+        base = task.get("base") or DEFAULT_BASE
+        diff = run_git(project, "diff", "--no-renames", "--name-only", f"{base}...{branch}")
+        files = [line.strip() for line in diff.stdout.splitlines() if line.strip()]
+        if files:
+            if all(_is_prose_review_path(path) for path in files):
+                return "fast", f"{len(files)} prose file(s)"
+            deep = [p for p in files if _is_deep_review_path(p)]
+            if deep:
+                return "deep", f"{len(deep)} security/release/workflow file(s)"
+            return "standard", f"{len(files)} file(s)"
+    return "standard", "no diff profile available"
+
+
+def review_gate_hint(profile: str) -> str:
+    if profile == "fast":
+        return (
+            "link check, docs/contract tests and the tree privacy scan; the full code "
+            "matrix is not needed for a prose-only diff"
+        )
+    if profile == "deep":
+        return (
+            "the full suite, lint/typecheck, privacy over tree and history, and the "
+            "security scan; this is a security/release/data/workflow change"
+        )
+    return "the full test suite, lint and type-check; a green CI run on the branch SHA may be cited"
+
+
+def review_latency(root: Path) -> dict:
+    """Claim -> verdict durations from the ledger, in minutes."""
+    claims: dict = {}
+    durations = []
+    for record in ledger_read(root):
+        action = record.get("action")
+        key = (record.get("role") or "", record.get("target") or "")
+        try:
+            stamp = datetime.datetime.fromisoformat(record.get("ts") or "")
+        except ValueError:
+            continue
+        if action == "review.claim":
+            claims[key] = stamp
+        elif action in ("review.pass", "review.fail") and key in claims:
+            durations.append((stamp - claims.pop(key)).total_seconds() / 60)
+    durations.sort()
+
+    def pct(share: float):
+        if not durations:
+            return None
+        return round(durations[min(len(durations) - 1, int(len(durations) * share))], 1)
+
+    return {"count": len(durations), "p50": pct(0.5), "p90": pct(0.9)}
+
+
+def review_packet(root: Path, role: str, task: dict, full: bool = False) -> str:
+    """Everything a Reviewer needs to start, in one screen."""
+    profile, reason = review_profile_for(root, role, task)
+    lease = review_lease_minutes(root)
+    lines = [
+        f"# Review packet: {role}/{task['id']} - {task['title']}",
+        f"- priority: {task['priority']} | status: {task['status']} | "
+        f"self_check: {task.get('self_check')} | review: {task.get('review_status')}",
+        f"- profile: {profile} ({reason})",
+        f"- author: {task.get('claimed_by') or '-'} | branch: {task.get('branch') or '-'} "
+        f"| base: {task.get('base') or DEFAULT_BASE} | pr: {task.get('pr') or '-'}",
+        f"- gates: {review_gate_hint(profile)}",
+    ]
+    project = project_of(root)
+    branch = task.get("branch") or ""
+    if branch and is_git_repo(project) and branch_exists(project, branch):
+        base = task.get("base") or DEFAULT_BASE
+        names = run_git(project, "diff", "--no-renames", "--name-only", f"{base}...{branch}")
+        files = [line.strip() for line in names.stdout.splitlines() if line.strip()]
+        if files:
+            lines.append("- changed files:")
+            lines += [f"  - {path}" for path in files[:20]]
+        stat = run_git(
+            project, "diff", "--no-renames", "--stat", f"{base}...{branch}"
+        ).stdout.strip()
+        if stat:
+            lines.append(f"- diffstat: {one_line(stat.splitlines()[-1])}")
+    for label, field in (
+        ("self-check note", "self_note"),
+        ("author evidence", "evidence"),
+        ("self-check artifacts", "self_artifacts"),
+    ):
+        value = (task.get(field) or "").strip()
+        if value:
+            lines.append(f"- {label}: {view_text(value, full)}")
+    lines += [
+        "- checklist: delivery/conformance; fidelity; internal consistency; "
+        "operational fitness; finish; evidence reproduces",
+        f"- claim: review {role} {task['id']} --claim --by <lane>  "
+        f"(lease {lease}m; --renew to extend)",
+        f"- verdict: review {role} {task['id']} --by <lane> --result pass "
+        "--evidence '<cmd @rev -> result>'",
+    ]
+    return "\n".join(lines)
+
+
+def review_claim_state(t: dict, minutes: int | None = None) -> tuple:
     """Return (lane, age_minutes, held) for a deliverable's review claim.
 
     A claim is a lease, not a lock: an undated or unreadable stamp counts as
@@ -5410,21 +6717,22 @@ def review_claim_state(t: dict) -> tuple:
     age = claim_age_minutes(t.get("review_claim_ts") or "")
     if age is None:
         return lane, None, False
-    return lane, age, age <= SLOT_TTL_MINUTES
+    return lane, age, age <= (REVIEW_LEASE_MINUTES if minutes is None else minutes)
 
 
-def review_is_held(t: dict) -> bool:
+def review_is_held(t: dict, minutes: int | None = None) -> bool:
     """True while a live claim pins a deliverable to one Reviewer lane."""
-    return review_claim_state(t)[2]
+    return review_claim_state(t, minutes)[2]
 
 
-def _claim_note(t: dict) -> str:
+def _claim_note(t: dict, minutes: int | None = None) -> str:
     """One line of claim state for the pulse and queue listings."""
-    lane, age, held = review_claim_state(t)
+    limit = REVIEW_LEASE_MINUTES if minutes is None else minutes
+    lane, age, held = review_claim_state(t, limit)
     if not lane:
         return "unclaimed"
     if held:
-        return f"held by {lane} ({age}m into the {SLOT_TTL_MINUTES}m lease)"
+        return f"held by {lane} ({age}m into the {limit}m lease, {limit - age}m left)"
     return f"claim by {lane} expired ({'undated' if age is None else f'{age}m'}) - take it over"
 
 
@@ -5444,8 +6752,9 @@ def busy_instances(root: Path) -> set:
             continue
         for agent in used_slots(root, prov):
             busy.add(pascal(agent))
+    lease = review_lease_minutes(root)
     for _role, t in iter_tasks(root):
-        if review_is_held(t):
+        if review_is_held(t, lease):
             busy.add(pascal(t["review_claim"]))
     return busy
 
@@ -5478,8 +6787,22 @@ def awaiting_review(root: Path) -> list:
 
 
 def open_review_items(root: Path) -> list:
-    """Deliverables awaiting review that no Reviewer lane currently holds."""
-    return [(name, t) for name, t in awaiting_review(root) if not review_is_held(t)]
+    """Deliverables awaiting review that no Reviewer lane currently holds.
+
+    Highest priority first, then oldest: a P0 prose fix must not wait behind a
+    P2 code review just because its role sorts later.
+    """
+    lease = review_lease_minutes(root)
+    items = [(name, t) for name, t in awaiting_review(root) if not review_is_held(t, lease)]
+    items.sort(
+        key=lambda item: (
+            PRIORITY_ORDER.get(item[1]["priority"], 9),
+            item[1]["created"],
+            item[0],
+            item[1]["id"],
+        )
+    )
+    return items
 
 
 def review_lane_notes(root: Path) -> list:
@@ -5519,7 +6842,7 @@ def _pulse_review_claim(root: Path, owner: str, handle: str, lane: str) -> bool:
             t.get("review", "required") == "na"
             or t.get("review_status") == "passed"
             or t["status"] not in ("review", "done")
-            or review_is_held(t)
+            or review_is_held(t, review_lease_minutes(root))
             or pascal(t.get("claimed_by") or "") == pascal(lane)
         ):
             return False
@@ -5531,18 +6854,19 @@ def _pulse_review_claim(root: Path, owner: str, handle: str, lane: str) -> bool:
         "review.claim",
         lane,
         handle,
-        f"pulse dispatch: {owner}/{handle} (lease {SLOT_TTL_MINUTES}m)",
+        f"pulse dispatch: {owner}/{handle} (lease {review_lease_minutes(root)}m)",
         "",
-        "reviewer",
+        owner,
     )
     return True
 
 
 def held_review_items(root: Path) -> list:
     """Every claim on the board, live or expired: (owner_role, task, lane, age)."""
+    lease = review_lease_minutes(root)
     out = []
     for name, t in awaiting_review(root):
-        lane, age, _held = review_claim_state(t)
+        lane, age, _held = review_claim_state(t, lease)
         if lane:
             out.append((name, t, lane, age))
     return out
@@ -5668,13 +6992,21 @@ def cmd_pulse(args: object) -> int:
     if not ready_by_role:
         print("- none")
     print(f"- awaiting independent review: {len(awaiting)} ({len(open_items)} unclaimed)")
+    review_lanes = len(instances_of(root, "reviewer"))
+    if open_items:
+        oldest = max(days_since(t.get("created") or "") for _, t in open_items)
+        print(
+            f"# review capacity: {review_lanes} lane(s), {len(open_items)} unclaimed, "
+            f"oldest {oldest}d - add a lane when unclaimed > {2 * max(review_lanes, 1)}"
+        )
     print()
 
     if awaiting:
         print(f"## deliverables awaiting review ({len(awaiting)})")
         for name, t in awaiting:
             print(
-                f"- {name}/{t['id']} [{t['priority']}/{t['status']}] {t['title']}  {_claim_note(t)}"
+                f"- {name}/{t['id']} [{t['priority']}/{t['status']}] {t['title']}  "
+                f"{_claim_note(t, review_lease_minutes(root))}"
             )
         print()
 
@@ -5684,7 +7016,9 @@ def cmd_pulse(args: object) -> int:
     # parallel instead of one task per lane per wake.
     # only a live claim blocks a lane; an expired one is up for takeover, which
     # is exactly the work the next pulse should hand out
-    claim_holders = {pascal(lane) for _own, _t, lane, age in claims if age < SLOT_TTL_MINUTES}
+    claim_holders = {
+        pascal(lane) for _own, _t, lane, age in claims if age < review_lease_minutes(root)
+    }
     capacity: dict[str, int] = {}
     for a in list_agents(root):
         role_name = resolve_role(a)
@@ -5718,15 +7052,33 @@ def cmd_pulse(args: object) -> int:
                 capacity[inst] -= 1
 
     limits = load_providers(root)
+    slot_holders = {pascal(a) for a in list_agents(root) if find_slot_provider(root, a)}
     free_slots = sum(
         max(cap - len(used_slots(root, prov)), 0)
         for prov, cap in limits.items()
         if prov != "default"
     )
-    if len(plan) > free_slots:
+    # A lane that already holds a lease does not need a second one; a lane without
+    # one does. Planning more new lanes than there are free slots is the article's
+    # stampede: every lane polls, few get served, and the retries cost more than the
+    # work. Defer the tail instead of handing out work nobody can start.
+    deferred = []
+    new_slot_lanes = [entry for entry in plan if pascal(entry[1]) not in slot_holders]
+    if len(new_slot_lanes) > free_slots:
+        allowed = free_slots
+        kept = []
+        for entry in plan:
+            if pascal(entry[1]) not in slot_holders:
+                if allowed <= 0:
+                    deferred.append(entry)
+                    continue
+                allowed -= 1
+            kept.append(entry)
+        plan = kept
         print(
-            f"# capacity: {len(plan)} assignment(s) ready, {free_slots} free provider "
-            "slot(s) - the rest waits for a lease to free"
+            f"# capacity: {len(new_slot_lanes)} lane(s) need a new slot, {free_slots} "
+            f"free - deferring {len(deferred)} assignment(s) instead of "
+            "over-subscribing the provider"
         )
     print("## dispatch plan")
     if not plan:
@@ -5734,6 +7086,13 @@ def cmd_pulse(args: object) -> int:
     for role, inst, task, title, review_owner in plan:
         tid = f"{review_owner}/{task['id']}" if review_owner else (task["id"] if task else "Review")
         print(f"- {inst:16s} <- {tid} [{role}] {title}")
+    if deferred:
+        print(
+            "# deferred until a lease frees: "
+            + ", ".join(
+                f"{entry[1]}<-{entry[2]['id'] if entry[2] else 'review'}" for entry in deferred
+            )
+        )
     print()
 
     if args.commit and plan:
@@ -5853,42 +7212,518 @@ def cmd_parallel(args) -> int:
     print(f"- TOTAL ready tasks: {ready_total}")
     print()
 
-    awaiting = 0
-    for name in list_roles(root):
-        for t in parse_tasks(task_file(root, name)):
-            if (
-                t.get("review", "required") != "na"
-                and t.get("review_status") != "passed"
-                and t["status"] in ("review", "done")
-            ):
-                awaiting += 1
-    print("## guidance")
-    focused = (
-        "ollama-cloud"
-        if "ollama-cloud" in limits
-        else next((p for p in limits if p != "default"), "ollama-cloud")
+    awaiting = 0
+    for name in list_roles(root):
+        for t in parse_tasks(task_file(root, name)):
+            if (
+                t.get("review", "required") != "na"
+                and t.get("review_status") != "passed"
+                and t["status"] in ("review", "done")
+            ):
+                awaiting += 1
+    print("## guidance")
+    focused = (
+        "ollama-cloud"
+        if "ollama-cloud" in limits
+        else next((p for p in limits if p != "default"), "ollama-cloud")
+    )
+    focused_free = max(limits.get(focused, 8) - len(used_slots(root, focused)), 0)
+    bulk = "deepseek" if "deepseek" in limits else focused
+    bulk_free = max(limits.get(bulk, 0) - len(used_slots(root, bulk)), 0)
+    running = sum(len(used_slots(root, p)) for p in limits if p != "default")
+    lanes = min(ready_total, focused_free + bulk_free)
+    print(f"- focused reasoning lanes ({focused}): {focused_free} free")
+    print(f"- bulk fanout lanes ({bulk}): {bulk_free} free")
+    print(f"- start up to {lanes} new lane(s) now (ready tasks: {ready_total})")
+    if running:
+        print(
+            f"- {running} lane(s) already hold a slot: hand the next task to a"
+            " running lane before spawning another (keeps memory and context warm)"
+        )
+    if awaiting:
+        review_lanes = len(instances_of(root, "reviewer"))
+        print(
+            f"- review queue: {awaiting} deliverable(s), {review_lanes} lane(s); "
+            f"add a Reviewer lane when the queue exceeds {2 * max(review_lanes, 1)}"
+        )
+    if ready_total > lanes:
+        print("- more ready work than slots: queue it by priority, do not oversubscribe")
+    print(
+        "- independent sub-tasks only: one writer per file, no two agents on the"
+        " same file, and never more lanes than the provider cap allows"
+    )
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# Coordination health
+#
+# Source: Anthropic, "Measuring multiagent systems" (accessed 2026-10-27),
+# https://www.anthropic.com/research/multiagent-systems - see
+# references/Coordination.md. The finding that shaped these checks is structural:
+# lanes that share a model, a context and a queue fail together, and a review
+# lane with no cross-check turns one blind spot into a systemic one. So this is
+# instrumentation, not advice: every check reads records the team already writes.
+# --------------------------------------------------------------------------- #
+
+COORD_OPEN = ("todo", "doing", "selfcheck", "blocked", "review")
+COORD_VERIFICATION_ROLES = ("reviewer", "security-auditor", "tester")
+COORD_VERDICT_FLOOR = 6
+COORD_MERGE_FLOOR = 4
+COORD_TRUST_FLOOR = 8
+COORD_VERDICT_SHARE = 0.75
+COORD_RECLAIM_DAYS = 7
+
+COORD_CHECK_TITLE = {
+    "diversity": "diversity - lanes that share a model, a context and a queue fail together",
+    "trust": "trust - a single source is provisional, a copied check is no check",
+    "turf": "turf - a conflicting directive is not a hostile agent",
+    "merge": "merge health - work that conflicts gets abandoned, not fixed",
+    "capacity": "capacity - a starved queue makes every lane poll and race",
+    "review": "review throughput - the queue cannot move faster than its lanes",
+}
+
+
+def _coord_finding(
+    code: str, check: str, severity: str, subject: str, detail: str, fix: str
+) -> dict:
+    return {
+        "code": code,
+        "check": check,
+        "severity": severity,
+        "subject": subject,
+        "detail": detail,
+        "fix": fix,
+    }
+
+
+def _signal(text) -> str:
+    """A comparison key that survives wording noise: lowercase words only."""
+    return re.sub(r"[^a-z0-9]+", " ", str(text or "").lower()).strip()
+
+
+def _evidence_body(value) -> str:
+    """The command/result line without the engine's appended evidence packet."""
+    text = str(value or "")
+    return re.split(r"\s\|\s(?:artifacts|baseline|replay):", text, maxsplit=1)[0].strip()
+
+
+def _ledger_verdicts(root: Path) -> dict:
+    """Reviewer verdicts by instance, from the append-only trail."""
+    out: dict = {}
+    for record in ledger_read(root):
+        action = record.get("action")
+        if action not in ("review.pass", "review.fail"):
+            continue
+        actor = pascal(record.get("actor") or "")
+        if not actor:
+            continue
+        row = out.setdefault(actor, {"pass": 0, "fail": 0})
+        row["pass" if action.endswith("pass") else "fail"] += 1
+    return out
+
+
+def _model_label(root: Path, lane: str) -> str:
+    entry = resolved_model(root, lane)
+    provider = (entry.get("provider") or "").strip()
+    model = (entry.get("model") or "").strip()
+    if provider and model:
+        return f"{provider}/{model}"
+    return model or provider
+
+
+def duplicate_task_pairs(root: Path, threshold: float = 0.6) -> list:
+    """Near-duplicate open tasks, as ``(percent, role, task, role, task)``.
+
+    One implementation for both `audit` (which prints them) and `coordination`
+    (which counts them as a diversity failure): two detectors drifting apart is
+    how a duplicate survives one gate and passes the other.
+    """
+    items = []
+    for name in list_roles(root):
+        for task in parse_tasks(task_file(root, name)):
+            if task["status"] in ("done", "dropped"):
+                continue
+            words = {w for w in re.findall(r"[a-z0-9]+", task["title"].lower()) if len(w) > 3}
+            items.append((name, task, words))
+    pairs = []
+    for i in range(len(items)):
+        for j in range(i + 1, len(items)):
+            name1, task1, words1 = items[i]
+            name2, task2, words2 = items[j]
+            if not words1 or not words2:
+                continue
+            jaccard = len(words1 & words2) / len(words1 | words2)
+            if jaccard >= threshold:
+                pairs.append((int(jaccard * 100), name1, task1, name2, task2))
+    return pairs
+
+
+def _recent_reclaims(root: Path) -> list:
+    cutoff = datetime.datetime.now() - datetime.timedelta(days=COORD_RECLAIM_DAYS)
+    rows = []
+    for record in ledger_read(root):
+        if record.get("action") != "task.reclaim":
+            continue
+        try:
+            stamp = datetime.datetime.fromisoformat(record.get("ts") or "")
+        except ValueError:
+            continue
+        if stamp >= cutoff:
+            rows.append(record)
+    return rows
+
+
+def coordination_report(root: Path) -> dict:
+    """Measure the multi-agent failure modes the records can actually show.
+
+    Every finding names the record it came from and the action that clears it;
+    nothing here invents a metric the team does not already write down.
+    """
+    tasks = all_tasks(root)
+    open_tasks = [(role, t) for role, t in tasks if t.get("status") in COORD_OPEN]
+    findings: list = []
+
+    # --- diversity: the same branch, the same work, the same blind spot -------
+    branches: dict = {}
+    shared_refs: dict = {}
+    for role, task in open_tasks:
+        branch = (task.get("branch") or "").strip()
+        if branch:
+            branches.setdefault(branch, []).append(f"{role}/{task['id']}")
+        shared = _signal(task.get("shared") or "")
+        if shared:
+            shared_refs.setdefault(shared, []).append(f"{role}/{task['id']}")
+
+    for branch, holders in sorted(branches.items()):
+        if len(holders) > 1:
+            findings.append(
+                _coord_finding(
+                    "C-DIV-BRANCH",
+                    "diversity",
+                    "high",
+                    branch,
+                    f"one branch is attached to {len(holders)} open task(s): " + ", ".join(holders),
+                    "give each task its own branch (`branch start` names it from the "
+                    "task id); a shared branch guarantees the second PR conflicts",
+                )
+            )
+    for pct, role1, task1, role2, task2 in duplicate_task_pairs(root):
+        findings.append(
+            _coord_finding(
+                "C-DIV-TASK",
+                "diversity",
+                "medium",
+                f"{role1}/{task1['id']} vs {role2}/{task2['id']}",
+                f"{pct}% similar titles: {task1['title']!r} / {task2['title']!r}",
+                "merge or re-scope the duplicate before two lanes produce the same "
+                "artifact; `task add` a link to the original instead",
+            )
+        )
+    for shared, holders in sorted(shared_refs.items()):
+        if len(holders) > 1:
+            findings.append(
+                _coord_finding(
+                    "C-DIV-SHARED",
+                    "diversity",
+                    "medium",
+                    shared,
+                    "one shared board/PR reference is claimed by " + ", ".join(holders),
+                    "one task per reference, or record which lane owns which part",
+                )
+            )
+
+    # A verification lane is independent only if it does not share the base
+    # model's blind spot; two Reviewer lanes on one model is the article's
+    # measured conformity failure, not a stylistic preference.
+    for role in COORD_VERIFICATION_ROLES:
+        lanes = instances_of(root, role)
+        if len(lanes) < 2:
+            continue
+        labels = {lane: _model_label(root, lane) for lane in lanes}
+        known = {label for label in labels.values() if label}
+        if len(known) == 1:
+            label = next(iter(known))
+            findings.append(
+                _coord_finding(
+                    "C-DIV-MODEL",
+                    "diversity",
+                    "high" if role == "reviewer" else "medium",
+                    ", ".join(lanes),
+                    f"every {role} lane resolves to the same model ({label}), so the "
+                    "independent check shares one set of blind spots",
+                    "set TEAMWORK_MODEL_ALT to a second model and run `model auto "
+                    "--apply`, or pin one lane with `model set <lane> --provider ... "
+                    "--model ...`",
+                )
+            )
+
+    # --- trust: echo, monoculture, no-finding-ever ---------------------------
+    for role, task in tasks:
+        if task.get("review_status") != "passed":
+            continue
+        author = _signal(_evidence_body(task.get("evidence") or ""))
+        reviewer = _signal(_evidence_body(task.get("review_evidence") or ""))
+        if len(author) >= 20 and author == reviewer:
+            findings.append(
+                _coord_finding(
+                    "C-TRUST-ECHO",
+                    "trust",
+                    "medium",
+                    f"{role}/{task['id']}",
+                    "the reviewer's evidence is the author's evidence verbatim, so the "
+                    "check may have been copied instead of run",
+                    "re-run the verification yourself and record your own command and "
+                    "result; the reviewer's line is the independent signal",
+                )
+            )
+
+    verdicts = _ledger_verdicts(root)
+    total_verdicts = sum(row["pass"] + row["fail"] for row in verdicts.values())
+    if total_verdicts >= COORD_VERDICT_FLOOR:
+        top_lane, top_row = max(
+            verdicts.items(), key=lambda item: item[1]["pass"] + item[1]["fail"]
+        )
+        top_total = top_row["pass"] + top_row["fail"]
+        if top_total / total_verdicts >= COORD_VERDICT_SHARE:
+            findings.append(
+                _coord_finding(
+                    "C-TRUST-MONOCULTURE",
+                    "trust",
+                    "medium",
+                    top_lane,
+                    f"{top_total} of {total_verdicts} verdicts came from one Reviewer lane",
+                    "fan the review queue across the Reviewer lanes (`pulse --commit` "
+                    "does this one per lane); one lane is one blind spot",
+                )
+            )
+    for lane, row in sorted(verdicts.items()):
+        if row["pass"] >= COORD_TRUST_FLOOR and row["fail"] == 0:
+            findings.append(
+                _coord_finding(
+                    "C-TRUST-NOFAIL",
+                    "trust",
+                    "low",
+                    lane,
+                    f"{row['pass']} passes and no finding ever recorded",
+                    "sample one passed deliverable end to end with a second Reviewer, "
+                    "or confirm the sample is genuinely defect-free",
+                )
+            )
+
+    # --- turf: reclaims are the visible edge of a lane war --------------------
+    reclaims = _recent_reclaims(root)
+    if reclaims:
+        who = ", ".join(
+            f"{record.get('actor') or '?'}->{record.get('target') or '?'}"
+            for record in reclaims[-4:]
+        )
+        findings.append(
+            _coord_finding(
+                "C-TURF-RECLAIM",
+                "turf",
+                "low",
+                f"{len(reclaims)} reclaim(s) in {COORD_RECLAIM_DAYS} days",
+                "recent take-overs: " + who,
+                "reclaim only a silent lane; the engine now refuses while the owner "
+                "holds a live slot. A disputed scope goes to the CEO, never to force",
+            )
+        )
+
+    # --- merge health: the article's measured collapse ------------------------
+    prs = parse_reviews(reviews_path(root))
+    live_states = ("open", "approved", "changes-requested")
+    total_prs = sum(1 for pr in prs if pr.get("status") in live_states + ("merged",))
+    merged = sum(1 for pr in prs if pr.get("status") == "merged")
+    if total_prs >= COORD_MERGE_FLOOR and merged / total_prs < 0.5:
+        findings.append(
+            _coord_finding(
+                "C-MERGE-RATE",
+                "merge",
+                "medium",
+                f"{merged}/{total_prs} merged",
+                "most opened PRs never landed; conflicting work is being abandoned "
+                "instead of rebased",
+                "rebase each branch on the default branch before review, keep one "
+                "writer per file, and re-scope a PR that conflicts twice",
+            )
+        )
+    project = project_of(root)
+    if is_git_repo(project):
+        abandoned = [
+            pr
+            for pr in prs
+            if pr.get("status") != "merged"
+            and pr.get("branch")
+            and not branch_exists(project, pr["branch"])
+        ]
+        if abandoned:
+            findings.append(
+                _coord_finding(
+                    "C-MERGE-ABANDONED",
+                    "merge",
+                    "high",
+                    f"{len(abandoned)} abandoned PR(s)",
+                    "branch gone while the PR is open: "
+                    + ", ".join(pr["id"] for pr in abandoned[:6]),
+                    "re-open the branch from the PR head or close the PR with a reason; "
+                    "silent abandonment is how work disappears",
+                )
+            )
+
+    # --- capacity: starved lanes race, over-subscribed lanes fail -------------
+    limits = load_providers(root)
+    reap_slots(root)
+    over, free = [], 0
+    for provider, cap in sorted(limits.items()):
+        if provider == "default":
+            continue
+        used = len(used_slots(root, provider))
+        free += max(cap - used, 0)
+        if used > cap:
+            over.append(f"{provider} {used}>{cap}")
+    if over:
+        findings.append(
+            _coord_finding(
+                "C-CAP-OVER",
+                "capacity",
+                "high",
+                ", ".join(over),
+                "more leases are held than the provider cap allows",
+                "release stale leases (`slot reap`) and never acquire past the cap",
+            )
+        )
+    latency = review_latency(root)
+    ready = 0
+    for role in list_roles(root):
+        queue = parse_tasks(task_file(root, role))
+        lookup = local_dep_map(queue)
+        cache: dict = {}
+        ready += sum(1 for task in queue if executable(task, lookup, cache, root))
+    if ready and free == 0:
+        findings.append(
+            _coord_finding(
+                "C-CAP-STARVED",
+                "capacity",
+                "medium",
+                f"{ready} ready / 0 free",
+                "executable work exists but every provider slot is leased",
+                "release finished leases, take work that needs no model call, or fan "
+                "out on another provider; do not let lanes poll for a slot",
+            )
+        )
+
+    open_reviews = open_review_items(root)
+    review_lanes = len(instances_of(root, "reviewer"))
+    if open_reviews:
+        oldest_review = max(days_since(t.get("created") or "") for _, t in open_reviews)
+        if len(open_reviews) > 2 * max(review_lanes, 1) or oldest_review >= 2:
+            findings.append(
+                _coord_finding(
+                    "C-REVIEW-BACKLOG",
+                    "review",
+                    "medium",
+                    f"{len(open_reviews)} unclaimed / {review_lanes} lane(s), "
+                    f"oldest {oldest_review}d",
+                    "the Reviewer queue is the team's throughput limit",
+                    "staff another Reviewer lane, send prose-only items to a fast "
+                    "review, and renew claims instead of re-claiming",
+                )
+            )
+
+    return {
+        "findings": findings,
+        "metrics": {
+            "open_tasks": len(open_tasks),
+            "ready_tasks": ready,
+            "prs": total_prs,
+            "merged": merged,
+            "merge_fraction": round(merged / total_prs, 2) if total_prs else None,
+            "verdicts": total_verdicts,
+            "reviewer_lanes": len(instances_of(root, "reviewer")),
+            "review_queue": len(
+                [
+                    item
+                    for item in awaiting_review(root)
+                    if not review_is_held(item[1], review_lease_minutes(root))
+                ]
+            ),
+            "review_claims": len(held_review_items(root)),
+            "review_p50_minutes": latency["p50"],
+            "review_p90_minutes": latency["p90"],
+            "free_slots": free,
+            "reclaims": len(reclaims),
+        },
+    }
+
+
+def _coordination_print(report: dict, root: Path) -> int:
+    findings = report["findings"]
+    severity_rank = {"high": 0, "medium": 1, "low": 2}
+    counts = {key: 0 for key in severity_rank}
+    for finding in findings:
+        counts[finding["severity"]] += 1
+    print(f"# Coordination health ({root})")
+    print(f"# {counts['high']} high, {counts['medium']} medium, {counts['low']} low finding(s)")
+    print()
+    for check, title in COORD_CHECK_TITLE.items():
+        rows = [f for f in findings if f["check"] == check]
+        rows.sort(key=lambda f: (severity_rank.get(f["severity"], 9), f["code"]))
+        print(f"## {check}")
+        print(f"# {title}")
+        if not rows:
+            print("- no finding")
+        for finding in rows:
+            print(
+                f"- [{finding['severity']}] {finding['code']} {finding['subject']}: "
+                f"{finding['detail']}"
+            )
+            print(f"  fix: {finding['fix']}")
+        print()
+    metrics = report["metrics"]
+    fraction = metrics["merge_fraction"]
+    print("## metrics")
+    print(f"- open tasks: {metrics['open_tasks']} ({metrics['ready_tasks']} ready)")
+    print(
+        f"- PRs: {metrics['merged']}/{metrics['prs']} merged"
+        + (f" ({fraction})" if fraction is not None else "")
     )
-    focused_free = max(limits.get(focused, 8) - len(used_slots(root, focused)), 0)
-    bulk = "deepseek" if "deepseek" in limits else focused
-    bulk_free = max(limits.get(bulk, 0) - len(used_slots(root, bulk)), 0)
-    running = sum(len(used_slots(root, p)) for p in limits if p != "default")
-    lanes = min(ready_total, focused_free + bulk_free)
-    print(f"- focused reasoning lanes ({focused}): {focused_free} free")
-    print(f"- bulk fanout lanes ({bulk}): {bulk_free} free")
-    print(f"- start up to {lanes} new lane(s) now (ready tasks: {ready_total})")
-    if running:
-        print(
-            f"- {running} lane(s) already hold a slot: hand the next task to a"
-            " running lane before spawning another (keeps memory and context warm)"
-        )
-    if awaiting:
-        print(f"- {awaiting} deliverable(s) await review; the Reviewer is a lane too")
-    if ready_total > lanes:
-        print("- more ready work than slots: queue it by priority, do not oversubscribe")
     print(
-        "- independent sub-tasks only: one writer per file, no two agents on the"
-        " same file, and never more lanes than the provider cap allows"
+        f"- Reviewer lanes: {metrics['reviewer_lanes']} | verdicts: "
+        f"{metrics['verdicts']} | free slots: {metrics['free_slots']}"
+    )
+    print(
+        f"- review queue: {metrics['review_queue']} unclaimed | claims: "
+        f"{metrics['review_claims']} | claim->verdict p50/p90: "
+        f"{metrics['review_p50_minutes']}/{metrics['review_p90_minutes']} min"
     )
+    print(f"- reclaims in {COORD_RECLAIM_DAYS} days: {metrics['reclaims']}")
+    return 0
+
+
+def cmd_coordination(args) -> int:
+    """`teamwork coordination [--strict] [--json] [--commit]` - health, not ceremony."""
+    import json
+
+    root = project_root(args)
+    report = coordination_report(root)
+    if getattr(args, "json", False):
+        print(json.dumps({"command": "coordination", **report}, indent=2, sort_keys=True))
+    else:
+        _coordination_print(report, root)
+    counts = {key: 0 for key in ("high", "medium", "low")}
+    for finding in report["findings"]:
+        counts[finding["severity"]] += 1
+    if getattr(args, "commit", False):
+        ledger_append(
+            root,
+            "coordination.check",
+            "ceo",
+            "",
+            f"{counts['high']} high / {counts['medium']} medium / {counts['low']} low finding(s)",
+        )
+    if getattr(args, "strict", False) and counts["high"]:
+        return 1
     return 0
 
 
@@ -5928,10 +7763,19 @@ EXTERNAL_SCHEMES = ("http://", "https://", "mailto:", "doi:", "ftp://")
 
 
 def iter_markdown(project: Path) -> list:
-    """Every markdown file a human might read, excluding caches and dependencies."""
+    """Every markdown file a human might read, excluding caches and dependencies.
+
+    The skip test is relative to ``project``. Testing the absolute parts instead
+    silently skipped every file when the project itself lives under ``.pi`` (a
+    per-instance worktree), which made ``links`` pass vacuously there.
+    """
     out = []
     for p in project.rglob("*.md"):
-        if any(part in SKIP_DIRS for part in p.parts):
+        try:
+            parts = p.relative_to(project).parts
+        except ValueError:
+            parts = p.parts
+        if any(part in SKIP_DIRS for part in parts):
             continue
         out.append(p)
     return sorted(out)
@@ -6045,7 +7889,9 @@ def link_report(project: Path, root: Path) -> dict:
 
 def cmd_links(args) -> int:
     root = project_root(args)
-    project = project_of(root)
+    # Inside one of our worktrees this is the worktree, so a lane checks the links
+    # it is about to submit rather than the checkout it happens to share.
+    project = work_repo(root)
     rep = link_report(project, root)
     issues = len(rep["broken"]) + len(rep["external_bad"]) + len(rep["bare"])
     if not args.no_reciprocity:
@@ -6134,7 +7980,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
     names = list_roles(root)
     tasks = all_tasks(root)
 
-    # 1 - acceptance criteria -------------------------------------------------
     s = _section("criteria", "acceptance criteria (machine records)")
     criteria = parse_criteria(criteria_path(root))
     if not criteria:
@@ -6171,7 +8016,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         )
     sections.append(s)
 
-    # 2 - layered tests -------------------------------------------------------
     s = _section("tests", "test layers (each owned and run by its own role)")
     records = parse_tests(tests_path(root))
     if not records:
@@ -6215,7 +8059,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         )
     sections.append(s)
 
-    # 3 - work in flight ------------------------------------------------------
     s = _section("work", "work in flight")
     buckets = {k: [] for k in ("todo", "doing", "selfcheck", "blocked", "review")}
     invalid = []
@@ -6240,7 +8083,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         s["blockers"].append(f"{len(invalid)} task(s) have an unknown status")
     sections.append(s)
 
-    # 4 - awaiting review -----------------------------------------------------
     s = _section("review", "awaiting independent review")
     awaiting = [
         (r, t)
@@ -6259,7 +8101,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         s["lines"].append("none")
     sections.append(s)
 
-    # 5 - review churn (a failing loop must escalate, not spin) ---------------
     s = _section("churn", "review churn")
     churn = [
         (r, t)
@@ -6285,7 +8126,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         s["lines"].append("none")
     sections.append(s)
 
-    # 6 - branches -----------------------------------------------------------
     s = _section("branches", "branches (merge and retire)")
     project = project_of(root)
     unmerged, leftover = [], []
@@ -6318,7 +8158,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         s["lines"].append("none")
     sections.append(s)
 
-    # 7 - overrides, provenance, liveness ------------------------------------
     s = _section("integrity", "gate overrides, provenance and liveness")
     forced, unprovenanced, silent = [], [], []
     for role, t in tasks:
@@ -6373,7 +8212,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         s["lines"].append("none")
     sections.append(s)
 
-    # 8 - disputes -----------------------------------------------------------
     s = _section("disputes", "open disputes")
     open_disputes = [d for d in disputes if d["status"] != "resolved"]
     for d in open_disputes:
@@ -6404,7 +8242,6 @@ def gate_report(root: Path, stale_days: int = 2, full: bool = False) -> dict:
         s["lines"].append("none")
     sections.append(s)
 
-    # 9 - audit trail --------------------------------------------------------
     s = _section("ledger", "audit trail")
     if ledger_cache_behind(root):
         s["lines"].append(
@@ -6539,17 +8376,27 @@ def archive_ensure_entry(root: Path, owner: str, t: dict, repo: Path | None = No
     return f"# archive: wrote the accepted-results entry for {branch} on the base"
 
 
-#: Credential rules of the shipped privacy gate. The archive mask borrows the
-#: gate's own rule table rather than re-declaring shapes: a hand-written mask
-#: drifted from the scanner twice (it covered 2 of the 5 credential rules and
-#: masked ``sk-learn-pipeline``, which the gate never reports), and the archive is
-#: the one place where a divergence between mask and gate is unrecoverable.
+#: Rules of the shipped privacy gate that the archive mask covers. The mask
+#: borrows the gate's own rule table rather than re-declaring shapes: a
+#: hand-written mask drifted from the scanner twice (it covered 2 of the 5
+#: credential rules and masked ``sk-learn-pipeline``, which the gate never
+#: reports), and the archive is the one place where a divergence between mask
+#: and gate is unrecoverable.
+#:
+#: The set is every rule the gate reports except the two it silences inside a
+#: quotation (``_QUOTED_PATH_RULES``): a path *shape* is not personal data, but
+#: an address is, and the gate keeps the identity rules armed on a quoted
+#: evidence line on purpose. Naming the two identity rules here is what stops
+#: the engine from writing an archive record the gate rejects - the review
+#: record is where a quoted address becomes permanent.
 CREDENTIAL_RULES = (
     "private-key",
     "api-token",
     "env-secret",
     "json-secret",
     "high-entropy-secret",
+    "personal-email",
+    "private-domain",
 )
 
 
@@ -6560,8 +8407,16 @@ def _privacy_scan():  # noqa: ANN202 - module handle, cached below
     directory can neither shadow the ``teamwork`` package nor leak into the
     process. ``None`` means the bundle is incomplete (an install that dropped
     ``scripts/``); the caller then records the text unmasked rather than guessing.
+
+    A scanner that is present but *fails to load* is a different case: it is a
+    defect, not an incomplete install, and silently returning ``None`` would
+    switch credential masking off in every record the team writes. So the
+    failure is reported once on ``stderr`` - naming the scanner path and the
+    exception - and not again, because the outcome is cached (``_PRIVACY_SCAN``
+    becomes ``None``, ``_PRIVACY_WARNED`` latches) and does not depend on the
+    value being masked.
     """
-    global _PRIVACY_SCAN
+    global _PRIVACY_SCAN, _PRIVACY_WARNED
     if _PRIVACY_SCAN is not _UNLOADED:
         return _PRIVACY_SCAN
     path = _resources.asset("scripts") / "privacy_scan.py"
@@ -6573,13 +8428,26 @@ def _privacy_scan():  # noqa: ANN202 - module handle, cached below
                 module = importlib.util.module_from_spec(spec)
                 spec.loader.exec_module(module)
                 _PRIVACY_SCAN = module
-        except Exception:  # noqa: BLE001 - a broken scanner must not break records
+        except Exception as exc:  # noqa: BLE001 - a broken scanner must not break records
+            # Keep the intent (records still get written) but not the silence:
+            # masking is OFF for the rest of the process, so the writer's caller
+            # must be able to see why. Same shape as the other warnings this
+            # module prints on stderr while writing records.
             _PRIVACY_SCAN = None
+            if not _PRIVACY_WARNED:
+                _PRIVACY_WARNED = True
+                print(
+                    f"teamwork: WARNING the privacy scanner {path} failed to load "
+                    f"({type(exc).__name__}: {exc}): records will be written "
+                    "with credential masking DISABLED until it is fixed",
+                    file=sys.stderr,
+                )
     return _PRIVACY_SCAN
 
 
 _UNLOADED = object()
 _PRIVACY_SCAN = _UNLOADED
+_PRIVACY_WARNED = False
 
 
 def mask_secret_shapes(text: str) -> str:
@@ -6587,14 +8455,29 @@ def mask_secret_shapes(text: str) -> str:
 
     An archive entry quotes another agent's words verbatim, so a verdict that
     proved a credential rule fires by quoting a fake token puts that token into
-    history. The mask is exactly the gate's own finding set: a value the gate
-    reports becomes ``<redacted-RULE>``, and a value it does not report is left
-    byte-identical, so ordinary prose, commit shas, ``sk-something`` helper names
-    and a JSON placeholder the gate accepts survive. Every value comes from the
-    gate's own ``scan_lines`` - the JSON rule included - so the mask cannot drift
-    by taking a regex directly and skipping the gate's placeholder, code-shape and
-    allow filters. The quoted claim ("a token on the exempted line is still
-    reported") remains readable.
+    history. The mask is the gate's own finding set minus the two path *shapes*
+    the gate itself silences inside a quotation (``home-path``,
+    ``agent-config``): a value the gate reports becomes ``<redacted-RULE>``, and
+    a value it does not report is left byte-identical, so ordinary prose, commit
+    shas, ``sk-something`` helper names, a JSON placeholder the gate accepts and
+    a role mailbox survive. Every value comes from the gate's own ``scan_lines``
+    - the JSON rule included - so the mask cannot drift by taking a regex
+    directly and skipping the gate's placeholder, code-shape and allow filters.
+    The quoted claim ("a token on the exempted line is still reported") remains
+    readable, and so does the finding around a redacted address: the ADDRESS is
+    replaced, not the evidence.
+
+    Contract when the scanner is unavailable (this function then returns the
+    text byte-identical, so the caller must not assume a mask happened):
+
+    * a bundle without ``scripts/privacy_scan.py`` - an incomplete install - is
+      a known state, and the text is recorded unmasked on purpose;
+    * a scanner that is present but raises while loading is a defect: the text
+      is still recorded unmasked (a broken scanner must not break records), but
+      ``_privacy_scan`` prints one ``teamwork: WARNING`` on stderr naming the
+      scanner path and the exception. Masking stays disabled for the rest of the
+      process and the warning is not repeated, so a caller that wants a hard
+      failure must surface that warning itself.
     """
     if not text:
         return text
@@ -6608,7 +8491,9 @@ def mask_secret_shapes(text: str) -> str:
     # placeholder, code-shape and allow filters, so a placeholder the gate accepts
     # (``${API_KEY}``, ``replace_me``) was rewritten in the immutable record.
     for finding in scanner.scan_lines(text, "", "archive", rules, ()):
-        value = finding.get("match") or ""
+        # The raw value is a Finding attribute, never a report item, so the
+        # scanner cannot publish it and this mask reads it explicitly.
+        value = finding.raw or ""
         if not value:
             continue
         rule = finding["rule"]
@@ -6831,16 +8716,6 @@ def commit_archive_merge_sha(
     return f"{message}\n# committed the archive rewrite on {base} at {close_sha}"
 
 
-def find_review_role_unused(root: Path, handle: str):
-    """(role, task) for a task id / title across every role queue."""
-    for role in list_roles(root):
-        tasks = parse_tasks(task_file(root, role))
-        idx = find_task(tasks, handle)
-        if idx is not None:
-            return role, tasks[idx], tasks, task_file(root, role), idx
-    return None, None, None, None, None
-
-
 def _review_claim(root: Path, args) -> int:
     """Take a deliverable off the shared review queue, or hand it back.
 
@@ -6849,17 +8724,22 @@ def _review_claim(root: Path, args) -> int:
     that the lanes collide on one deliverable and leave the rest unreviewed.
     """
     claim, release = bool(args.claim), bool(args.release)
-    if claim and release:
-        die("--claim and --release are mutually exclusive", 2)
+    renew = bool(getattr(args, "renew", False))
+    if sum((claim, release, renew)) > 1:
+        die("--claim, --release and --renew are mutually exclusive", 2)
     if not (args.agent and args.handle):
-        die("usage: review <role> <T-id> --claim|--release --by <Reviewer instance>", 2)
+        die("usage: review <role> <T-id> --claim|--release|--renew --by <Reviewer instance>", 2)
     if args.result:
-        die(f"--claim/--release do not take --result {args.result}; the verdict is separate", 2)
+        die(
+            f"--claim/--release/--renew do not take --result {args.result}; the verdict is separate",
+            2,
+        )
     role = resolve_role(args.agent)
     reviewer, rrole = validate_actor(root, args.by or "reviewer", "reviewer", allow_role=False)
     if rrole != "reviewer":
         die(f"only the Reviewer role may hold a review (you passed {reviewer}).", 2)
-    verb = "claim" if claim else "release"
+    verb = "renew" if renew else ("claim" if claim else "release")
+    lease = review_lease_minutes(root)
     path = task_file(root, role)
     with lock(root / DIR_RUNTIME / DIR_LOCKS / f"role-{role}.lock"):
         tasks = parse_tasks(path)
@@ -6881,12 +8761,30 @@ def _review_claim(root: Path, args) -> int:
             die(
                 f"{reviewer} produced {t['id']} and cannot review it; another lane must take it.", 2
             )
-        lane, age, held = review_claim_state(t)
+        lane, age, held = review_claim_state(t, lease)
+        if renew:
+            if not lane:
+                die(f"{role}/{t['id']} is not claimed; take it with --claim", 2)
+            if pascal(lane) != pascal(reviewer):
+                die(f"{role}/{t['id']} is held by {lane}; only that lane renews its lease", 2)
+            t["review_claim_ts"] = claim_stamp()
+            write_tasks(path, tasks, role)
+            ledger_append(
+                root,
+                "review.renew",
+                reviewer,
+                t["id"],
+                f"{role}/{t['id']} lease renewed for {lease}m",
+                "",
+                role,
+            )
+            print(f"teamwork: {reviewer} renewed {role}/{t['id']} for {lease} min")
+            return 0
         if claim:
             if held and pascal(lane) != pascal(reviewer):
                 die(
                     f"{role}/{t['id']} is held by {lane} ({age}m into the "
-                    f"{SLOT_TTL_MINUTES}m lease): let it finish, or wait for the lease "
+                    f"{lease}m lease): let it finish, renew it, or wait for the lease "
                     "to expire and take it over",
                     2,
                 )
@@ -6903,14 +8801,14 @@ def _review_claim(root: Path, args) -> int:
                 "review.claim",
                 reviewer,
                 t["id"],
-                f"{role}/{t['id']} claimed for review (lease {SLOT_TTL_MINUTES}m){took_over}",
+                f"{role}/{t['id']} claimed for review (lease {lease}m){took_over}",
                 "",
-                "reviewer",
+                role,
             )
             print(
-                f"teamwork: {reviewer} holds {role}/{t['id']} for {SLOT_TTL_MINUTES} min: "
+                f"teamwork: {reviewer} holds {role}/{t['id']} for {lease} min: "
                 f"review {role} {t['id']} --by {reviewer} --result pass --evidence "
-                "'<cmd @rev -> result>' or hand it back with --release"
+                "'<cmd @rev -> result>', renew with --renew, or hand it back with --release"
             )
             return 0
         if not lane:
@@ -6939,7 +8837,7 @@ def _review_claim(root: Path, args) -> int:
             t["id"],
             f"{role}/{t['id']} released by {lane}{forced}",
             "",
-            "reviewer",
+            role,
         )
         print(f"teamwork: {role}/{t['id']} is back on the shared review queue")
         return 0
@@ -6947,9 +8845,31 @@ def _review_claim(root: Path, args) -> int:
 
 def cmd_review(args) -> int:
     root = project_root(args)
+    if getattr(args, "packet", False) and (
+        args.claim or args.release or getattr(args, "renew", False) or args.result
+    ):
+        die("--packet is read-only; claim or verdict separately", 2)
     if args.queue:
-        return _review_queue(root, full=bool(getattr(args, "full", False)))
-    if getattr(args, "claim", False) or getattr(args, "release", False):
+        return _review_queue(
+            root,
+            full=bool(getattr(args, "full", False)),
+            packet=bool(getattr(args, "packet", False)),
+        )
+    if getattr(args, "packet", False):
+        if not (args.agent and args.handle):
+            die("usage: review <role> <T-id> --packet [--full]", 2)
+        role = resolve_role(args.agent)
+        tasks = parse_tasks(task_file(root, role))
+        idx = find_task(tasks, args.handle)
+        if idx is None:
+            die(f"no task '{args.handle}' for {role}", 2)
+        print(review_packet(root, role, tasks[idx], full=bool(getattr(args, "full", False))))
+        return 0
+    if (
+        getattr(args, "claim", False)
+        or getattr(args, "release", False)
+        or getattr(args, "renew", False)
+    ):
         return _review_claim(root, args)
     if not (args.agent and args.handle):
         die("usage: review <role> <T-id> --by <Reviewer> --result pass|fail [--evidence ...]")
@@ -6985,7 +8905,7 @@ def cmd_review(args) -> int:
                 f"{reviewer} produced {t['id']} and cannot review it; "
                 "an independent instance must review."
             )
-        lane, age, held = review_claim_state(t)
+        lane, age, held = review_claim_state(t, review_lease_minutes(root))
         if lane and pascal(lane) != pascal(reviewer):
             print(
                 f"teamwork: NOTE {role}/{t['id']} is held by {lane} "
@@ -7179,7 +9099,8 @@ def cmd_review(args) -> int:
     return 0
 
 
-def _review_queue(root: Path, full: bool = False) -> int:
+def _review_queue(root: Path, full: bool = False, packet: bool = False) -> int:
+    lease = review_lease_minutes(root)
     rows = []
     for name in list_roles(root):
         for t in parse_tasks(task_file(root, name)):
@@ -7187,17 +9108,25 @@ def _review_queue(root: Path, full: bool = False) -> int:
                 continue
             if t.get("review_status") == "passed" or t["status"] == "dropped":
                 continue
-            rows.append((PRIORITY_ORDER.get(t["priority"], 9), name, t))
+            rows.append((PRIORITY_ORDER.get(t["priority"], 9), t.get("created") or "", name, t))
     print(f"# Reviewer queue ({root})")
     if not rows:
         print("- nothing awaiting review")
         return 0
-    rows.sort(key=lambda r: (r[0], r[1], r[2]["id"]))
-    for _prio, name, t in rows:
+    rows.sort(key=lambda r: (r[0], r[1], r[2], r[3]["id"]))
+    if packet:
+        for _prio, _created, name, t in rows:
+            print(review_packet(root, name, t, full))
+            print()
+        return 0
+    for _prio, _created, name, t in rows:
+        profile, _reason = review_profile_for(root, name, t)
+        age = days_since(t.get("created") or "") if t.get("created") else 0
         print(
             f"- {name} {t['id']} [{t['priority']}/{t['status']}] {t['title']}"
-            f"  review_status={t.get('review_status', 'pending')}"
-            f" claim: {_claim_note(t)}"
+            f"  profile={profile} aged={age}d"
+            f" review_status={t.get('review_status', 'pending')}"
+            f" claim: {_claim_note(t, lease)}"
             f" self_check={t.get('self_check', 'pending')}"
             + (f" branch={t['branch']}" if t.get("branch") else "")
             + (f" pr={t['pr']}" if t.get("pr") else "")
@@ -7208,10 +9137,20 @@ def _review_queue(root: Path, full: bool = False) -> int:
             print(f"    findings so far: {view_text(t['findings'], full)}")
     print()
     lanes = review_lane_notes(root)
-    unclaimed = sum(1 for _prio, _name, t in rows if not review_is_held(t))
-    print(f"# {len(rows)} deliverable(s) to review ({unclaimed} unclaimed)")
+    lane_count = len(instances_of(root, "reviewer"))
+    unclaimed = sum(1 for _prio, _created, _name, t in rows if not review_is_held(t, lease))
+    oldest = max(
+        (days_since(t.get("created") or "") for _p, _c, _n, t in rows if t.get("created")),
+        default=0,
+    )
+    print(f"# {len(rows)} deliverable(s) to review ({unclaimed} unclaimed), oldest {oldest}d")
     print("# lanes: " + (", ".join(lanes) if lanes else "no Reviewer instance staffed"))
+    print(
+        f"# capacity: {lane_count} lane(s); add a Reviewer lane when unclaimed > "
+        f"{2 * max(lane_count, 1)}"
+    )
     print("# a review is claimed work: one lane takes one deliverable, then verdicts it")
+    print("#   review <role> <T-id> --packet   # profile, diff, gates, checklist")
     print("#   review <role> <T-id> --claim --by <Reviewer-instance>   # pin it to your lane")
     print(
         "#   review <role> <T-id> --by <Reviewer-instance> --result pass --evidence '<cmd @rev -> result>'"
@@ -7219,9 +9158,10 @@ def _review_queue(root: Path, full: bool = False) -> int:
     print(
         "#   review <role> <T-id> --by <Reviewer-instance> --result fail --findings '<defect + evidence>'"
     )
+    print("#   review <role> <T-id> --renew --by <Reviewer-instance>   # extend a long review")
     print(
         f"#   review <role> <T-id> --release --by <Reviewer-instance>   # hand it back "
-        f"(a claim lapses after {SLOT_TTL_MINUTES}m)"
+        f"(a claim lapses after {lease}m)"
     )
     return 0
 
@@ -7695,6 +9635,16 @@ def _audit_section(root: Path, names: list, args) -> int:
     return hits
 
 
+def _task_has_execution_evidence(t: dict) -> bool:
+    """True when the task record carries proof that something was executed.
+
+    A review pass writes review_evidence and a self-check writes self_note; a task
+    closed by hand writes evidence. The audit's question is "was this verified?",
+    not "was the evidence field used?", so all three count.
+    """
+    return any((t.get(key) or "").strip() for key in ("evidence", "review_evidence", "self_note"))
+
+
 def _audit_submitted_for_review_without_a_self_chec(root: Path, names: list, args) -> int:
     print("## submitted for review without a self-check (skipped their own test)")
     hits = 0
@@ -7704,6 +9654,9 @@ def _audit_submitted_for_review_without_a_self_chec(root: Path, names: list, arg
                 t.get("review", "required") != "na"
                 and t.get("self_check") not in ("passed", "na")
                 and t["status"] in ("review", "done")
+                # A forced review pass records why the self-check was skipped; the
+                # force is the audit trail, so re-reporting it every run is noise.
+                and not (t.get("forced") or "").strip()
             ):
                 print(
                     f"- {name} {t['id']} [{t['status']}] {t['title']} "
@@ -7720,7 +9673,12 @@ def _audit_done_without_evidence_fabricated_complet(root: Path, names: list, arg
     hits = 0
     for name in names:
         for t in parse_tasks(task_file(root, name)):
-            if t["status"] == "done" and not t.get("evidence"):
+            # `done` is normally set by a review pass, which records its proof in
+            # review_evidence (and self_note for the author's own run); only a task
+            # closed by hand relies on `evidence` alone. Any of the three is a
+            # record of execution, so any of them satisfies the anti-hallucination
+            # gate - testing `evidence` alone flagged every properly reviewed task.
+            if t["status"] == "done" and not _task_has_execution_evidence(t):
                 print(f"- {name} {t['id']} {t['title']}")
                 hits += 1
     if not hits:
@@ -7751,31 +9709,16 @@ def _audit_stale_in_progress(root: Path, names: list, args) -> int:
 
 def _audit_possible_duplicate_tasks_across_agents(root: Path, names: list, args) -> int:
     print("## possible duplicate tasks across agents")
-    items = []
-    for name in names:
-        for t in parse_tasks(task_file(root, name)):
-            if t["status"] in ("done", "dropped"):
-                continue
-            words = {w for w in re.findall(r"[a-z0-9]+", t["title"].lower()) if len(w) > 3}
-            items.append((name, t, words))
-    hits = 0
-    for i in range(len(items)):
-        for j in range(i + 1, len(items)):
-            n1, t1, w1 = items[i]
-            n2, t2, w2 = items[j]
-            if not w1 or not w2:
-                continue
-            jaccard = len(w1 & w2) / len(w1 | w2)
-            if jaccard >= 0.6:
-                print(
-                    f"- {int(jaccard * 100)}% similar: {n1}:{t1['id']} "
-                    f"{t1['title']!r}  <->  {n2}:{t2['id']} {t2['title']!r}"
-                )
-                hits += 1
-    if not hits:
+    pairs = duplicate_task_pairs(root)
+    for pct, name1, task1, name2, task2 in pairs:
+        print(
+            f"- {pct}% similar: {name1}:{task1['id']} "
+            f"{task1['title']!r}  <->  {name2}:{task2['id']} {task2['title']!r}"
+        )
+    if not pairs:
         print("- none")
     print()
-    return hits
+    return len(pairs)
 
 
 def _audit_memory_caps(root: Path, names: list, args) -> int:
@@ -8083,7 +10026,7 @@ def _audit_audit_trail_append_only_hash_chained(root: Path, names: list, args) -
         hits += 1
     if records and not problems_ledger:
         print(f"- {len(records)} records, chain intact, head {records[-1]['hash'][:16]}")
-    manifest = docs_dir(root) / F_MANIFEST
+    manifest = work_docs_dir(root) / F_MANIFEST
     if manifest.exists():
         try:
             import json
@@ -8208,26 +10151,46 @@ def _audit_git_archival_lfs_large_files(root: Path, names: list, args) -> int:
             print("- .gitattributes has no Git LFS rules: run `teamwork.py repo`")
             hits += 1
         else:
-            big = []
+            all_files = []
             for p_ in project.rglob("*"):
                 if not p_.is_file() or any(
                     part in {".git", ".pi"} | SKIP_DIRS for part in p_.parts
                 ):
                     continue
+                all_files.append(p_.relative_to(project).as_posix())
+            mismatched = [rel for rel in all_files if lfs_text_mismatch(project, rel)]
+            if mismatched:
+                print(
+                    f"- {len(mismatched)} text file(s) routed into Git LFS by a "
+                    ".gitattributes pattern, e.g. "
+                    + ", ".join(mismatched[:3])
+                    + "\n  LFS is for binaries: a document in LFS is a pointer for "
+                    "every reader without an LFS client. Drop the pattern from "
+                    ".gitattributes, or make the content binary."
+                )
+                hits += 1
+            big = []
+            for rel in all_files:
                 try:
-                    if p_.stat().st_size >= 1_000_000:
-                        big.append(p_.relative_to(project).as_posix())
+                    if (project / rel).stat().st_size > LFS_MAX_BYTES:
+                        big.append(rel)
                 except OSError:
                     pass
-            untracked = [b for b in big if not lfs_tracked(project, b)]
+            binaries = [b for b in big if is_binary_content(project / b)]
+            untracked = [b for b in binaries if not lfs_tracked(project, b)]
             if untracked:
                 print(
-                    f"- {len(untracked)} large file(s) not LFS-tracked, e.g. "
+                    f"- {len(untracked)} large binary file(s) not LFS-tracked, e.g. "
                     + ", ".join(untracked[:3])
                 )
                 hits += 1
-            else:
-                print(f"- LFS rules present; {len(big)} large file(s), all tracked")
+            if not untracked:
+                text = len(big) - len(binaries)
+                note = f"; {text} large text record(s) exempt from the threshold" if text else ""
+                print(
+                    f"- LFS rules present; {len(binaries)} large binary file(s), "
+                    f"all LFS-tracked{note}"
+                )
     else:
         print("- no git repository yet: run `teamwork.py repo`")
         hits += 1
@@ -8239,7 +10202,10 @@ def _audit_git_archival_lfs_large_files(root: Path, names: list, args) -> int:
 def _audit_markdown_link_health_broken_malformed_ba(root: Path, names: list, args) -> int:
     hits = 0
     print("## markdown link health (broken / malformed / bare / missing back-links)")
-    rep = link_report(project_of(root), root)
+    # Same rule as cmd_links: measure the tree the caller is in. project_of()
+    # answers for the main checkout, so inside a worktree this section reported
+    # "none" no matter what the lane's own documents contained.
+    rep = link_report(work_repo(root), root)
     link_issues = (
         len(rep["broken"]) + len(rep["external_bad"]) + len(rep["bare"]) + len(rep["missing_back"])
     )
@@ -8272,14 +10238,78 @@ def _print_dispute(d: dict) -> None:
         print(f"    ruling: signed=[{', '.join(d['signed'])}] {d['decision']}")
 
 
-def _dispute_parties(dispute: dict = None) -> set:
-    """The roles a dispute is between; neither may rule it."""
+def _dispute_party_instances(root: Path, dispute: dict = None) -> set:
+    """The instances a dispute is between, in their canonical spelling.
+
+    A dispute names agents, not roles: ``raised_by``/``against`` hold the instance
+    that opened it and the instance it was opened against. Comparing them at role
+    level (the old ``resolve_role`` test) dropped a whole role from the panel as
+    soon as one of its instances was a party, which locked the uninvolved
+    instances of that same role out of the neutral seat.
+
+    A dispute raised against a bare role name speaks for every instance of that
+    role, so the whole role counts as a party here.
+    """
     if not dispute:
         return set()
-    return {
-        resolve_role(dispute.get("raised_by") or ""),
-        resolve_role(dispute.get("against") or ""),
-    }
+    out = set()
+    for field in ("raised_by", "against"):
+        name = pascal(dispute.get(field) or "")
+        if not name:
+            continue
+        role = resolve_role(name)
+        instances = {pascal(i) for i in instances_of(root, role)}
+        if name in instances:
+            out.add(name)
+        else:
+            out.update(instances)
+    return out
+
+
+def _dispute_party_instance(root: Path, dispute: dict, instance: str) -> bool:
+    """True when *this instance* is named in ``raised_by``/``against``.
+
+    The guarantee is per agent, not per role: Reviewer-2 may be a party to a
+    dispute while Reviewer-1 is not, and only Reviewer-2 is locked out of it.
+    """
+    if not dispute:
+        return False
+    return pascal(instance or "") in _dispute_party_instances(root, dispute)
+
+
+def _actor_is_dispute_party(root: Path, dispute: dict, actor: str, role: str) -> bool:
+    """True when the actor may not sign or rule the dispute it is party to.
+
+    A concrete instance is a party when it is named in the dispute. A bare role
+    name speaks for the whole role, so it is a party when ANY of its instances
+    is - otherwise a party could sign under its role name and slip past the
+    instance-level rule.
+    """
+    instances = instances_of(root, role)
+    if pascal(actor or "") in {pascal(i) for i in instances}:
+        return _dispute_party_instance(root, dispute, actor)
+    return any(_dispute_party_instance(root, dispute, inst) for inst in instances)
+
+
+def _role_has_neutral_instance(root: Path, role: str, dispute: dict) -> bool:
+    """True when the role has an instance that is not a party to the dispute.
+
+    A role leaves the panel only when EVERY one of its instances is a party:
+    then no agent of that role can sit, so the role cannot be staffed neutrally.
+    """
+    instances = instances_of(root, role)
+    if not instances:
+        return False
+    if not dispute:
+        return True
+    return any(not _dispute_party_instance(root, dispute, inst) for inst in instances)
+
+
+def _role_is_party_role(root: Path, role: str, dispute: dict) -> bool:
+    """True when at least one instance of the role is a party to the dispute."""
+    if not dispute:
+        return False
+    return any(_dispute_party_instance(root, dispute, inst) for inst in instances_of(root, role))
 
 
 def required_tribunal(root: Path, dispute: dict = None) -> list:
@@ -8287,19 +10317,40 @@ def required_tribunal(root: Path, dispute: dict = None) -> list:
 
     The CEO always sits. CTO and CFO join when staffed. The Reviewer takes the
     remaining neutral seat, because a slim roster staffs neither CTO nor CFO and a
-    panel of one would let the CEO sign and resolve their own case. A role that is
-    itself a party never sits, so a ruling is never issued by the side it decides
-    for. Only roles that really have an instance are returned - an invented signer
-    cannot sign and would deadlock every escalated dispute.
+    panel of one would let the CEO sign and resolve their own case. A role is
+    excluded only when EVERY one of its instances is a party, so an uninvolved
+    instance of a party role can still take the neutral seat - the case that
+    locked the third Reviewer out of a Reviewer-vs-Reviewer dispute. Only roles
+    that really have an instance are returned - an invented signer cannot sign and
+    would deadlock every escalated dispute.
     """
-    parties = _dispute_parties(dispute)
-    members = [r for r in ("ceo", "cto", "cfo") if r not in parties and instances_of(root, r)]
-    if len(members) < TRIBUNAL_MIN_SIGNERS and "reviewer" not in parties:
-        if instances_of(root, "reviewer"):
-            members.append("reviewer")
+    members = [r for r in ("ceo", "cto", "cfo") if _role_has_neutral_instance(root, r, dispute)]
+    if _role_has_neutral_instance(root, "reviewer", dispute) and (
+        len(members) < TRIBUNAL_MIN_SIGNERS or _role_is_party_role(root, "reviewer", dispute)
+    ):
+        # The Reviewer takes the neutral seat. It also takes it when it is a party
+        # role with an uninvolved instance: the role was only on the panel by
+        # accident then, and that instance is the neutral seat the charter names.
+        members.append("reviewer")
     return members
 
 
+def _neutral_signer(root: Path, dispute: dict, members: list) -> str:
+    """A concrete instance that may sign and rule: on the panel, not a party.
+
+    The panel lists roles, but the party rule is per instance, so a role on the
+    panel can still be the party - and the notice must not name it as the signer.
+    """
+    for role in members:
+        instances = instances_of(root, role)
+        if not any(_dispute_party_instance(root, dispute, inst) for inst in instances):
+            return role
+        for inst in instances:
+            if not _dispute_party_instance(root, dispute, inst):
+                return inst
+    return ""
+
+
 def _dispute_tribunal_notice(root: Path, d: dict) -> None:
     members = required_tribunal(root, d)
     print("teamwork: this dispute needs the tribunal - escalate it now.")
@@ -8307,9 +10358,9 @@ def _dispute_tribunal_notice(root: Path, d: dict) -> None:
     print(f"  1) python3 teamwork.py dispute escalate {d['id']} --by {d['raised_by']}")
     print(f"  2) the tribunal ({', '.join(members)}) discusses and each signs:")
     print(f"     dispute sign {d['id']} --by {'|'.join(members)}")
-    signers = [r for r in members if r not in _dispute_parties(d)] or members
-    if signers:
-        print(f"  3) dispute resolve {d['id']} --by {signers[0]} --decision '<binding ruling>'")
+    signer = _neutral_signer(root, d, members)
+    if signer:
+        print(f"  3) dispute resolve {d['id']} --by {signer} --decision '<binding ruling>'")
     else:
         print("  3) nobody independent is staffed: add a reviewer, then resolve")
     print("  4) record the ruling in docs/Team/Decisions.md")
@@ -8422,6 +10473,16 @@ def cmd_dispute_sign(args) -> int:
         members = required_tribunal(root, d)
         if who not in members:
             die(f"only the tribunal may sign: {', '.join(members)}")
+        if _actor_is_dispute_party(root, d, actor, arole):
+            # The party rule is per instance: a role-mate is not a party, but the
+            # agent the dispute was raised against never signs its own case. The
+            # panel check runs first, so an actor off the panel still gets the
+            # panel message it always got.
+            die(
+                f"{d['id']}: {actor} is a party to this dispute and cannot sign it. "
+                f"Escalate it and let {', '.join(members)} decide",
+                2,
+            )
         if who not in d["signed"]:
             d["signed"].append(who)
         d["updated"] = today_iso()
@@ -8453,19 +10514,16 @@ def cmd_dispute_resolve(args) -> int:
         panel = required_tribunal(root, d)
         if arole not in panel:
             die(f"only the tribunal may resolve: {', '.join(panel)}")
-        parties = {
-            resolve_role(d.get("raised_by") or ""),
-            resolve_role(d.get("against") or ""),
-        }
-        if who in parties:
-            # A dispute is never decided by the side it decides for. Escalate it so a
-            # neutral member signs first; forcing it needs a written reason (F3).
-            what = (
-                f"{d['id']}: {who} is a party to this dispute and cannot rule it. "
-                f"Escalate it and let {', '.join(required_tribunal(root, d))} decide"
-            )
-            if not (args.force or "").strip():
-                die(f"{what}. Forcing it needs a written reason.", 2)
+        if _actor_is_dispute_party(root, d, actor, arole):
+            # A dispute is never decided by the side it decides for. The party test
+            # is per instance (a role-mate is not a party), and it is absolute:
+            # --force waives the signature requirement, never the party rule, so
+            # no party can rule its own dispute however good its reason reads.
+            die(
+                f"{d['id']}: {actor} is a party to this dispute and cannot rule it. "
+                f"Escalate it and let {', '.join(panel)} decide",
+                2,
+            )
         if d["escalated"]:
             members = required_tribunal(root, d)
             missing = [r for r in members if r not in d["signed"]]
@@ -8528,11 +10586,6 @@ def cmd_dispute_list(args) -> int:
     return 0
 
 
-def reporting_order() -> list[str]:
-    """Roles in reporting order, parents before children."""
-    return [r for r in ROLE_REPORT_ORDER if r in ROLE_PARENT]
-
-
 def reporting_children(parent: str) -> list[str]:
     """Direct reports of ``parent``, in reporting order."""
     return [r for r in ROLE_REPORT_ORDER if ROLE_PARENT.get(r) == parent]
@@ -8651,20 +10704,64 @@ def cmd_agents_md(args) -> int:
     return 0
 
 
-def _fetch_source(source: Path, remote: str, branch: str) -> tuple[bool, str]:
-    """Fetch ``remote/branch`` into ``source``. Returns ``(ok, detail)``."""
+def _source_ref(source: Path, remote: str, branch: str) -> tuple[str, str]:
+    """Resolve a refresh pin to ``(kind, commit)``, or ``("", "")``.
+
+    A pin names either a **branch** - fetched into ``refs/remotes/<remote>/<name>``
+    by a plain ``git fetch`` - or a **tag**, which a fetch by name leaves in
+    ``FETCH_HEAD`` only (``git fetch origin v1.1.2`` never creates
+    ``refs/remotes/origin/v1.1.2``, and ``git clone --branch`` accepts a tag
+    exactly once). Both spellings are tried, branch first, and the caller is told
+    which one answered so it can move the checkout the way that kind allows.
+    """
+    for kind, ref in (
+        ("branch", f"refs/remotes/{remote}/{branch}"),
+        ("tag", f"refs/tags/{branch}"),
+    ):
+        got = run_git(source, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+        if got.returncode == 0 and got.stdout.strip():
+            return kind, got.stdout.strip()
+    return "", ""
+
+
+def _fetch_source(source: Path, remote: str, branch: str) -> tuple[bool, str, str, str]:
+    """Fetch the ``branch`` pin into ``source`` -> ``(ok, detail, kind, commit)``.
+
+    ``kind`` is ``"branch"`` or ``"tag"`` and ``commit`` the full sha, so
+    ``_update_source`` can pick a fast-forward or a detached move without guessing
+    from the printed detail.
+    """
     got = run_git(source, "fetch", "--prune", "--quiet", remote, branch)
     if got.returncode != 0:
         tail = (got.stderr or got.stdout).strip().splitlines()
-        return False, tail[-1] if tail else "fetch failed"
-    rev = run_git(source, "rev-parse", "--short", f"{remote}/{branch}")
-    if rev.returncode != 0:
-        return False, f"no {remote}/{branch} after fetch"
-    return True, rev.stdout.strip()
+        missing = tail[-1] if tail else "fetch failed"
+        return False, f"no branch or tag {branch} on {remote}: {missing}", "", ""
+    kind, commit = _source_ref(source, remote, branch)
+    if not kind:
+        # The name exists (the fetch above succeeded) but is not a branch: fetch it
+        # as a tag ref so ``refs/tags/<name>`` resolves and stays identifiable.
+        tagged = run_git(
+            source, "fetch", "--quiet", remote, f"refs/tags/{branch}:refs/tags/{branch}"
+        )
+        if tagged.returncode == 0:
+            kind, commit = _source_ref(source, remote, branch)
+    if not kind:
+        return False, f"no branch {remote}/{branch} and no tag {branch} after fetch", "", ""
+    short = run_git(source, "rev-parse", "--short", commit).stdout.strip() or commit[:7]
+    if kind == "tag":
+        return True, f"pinned to tag {branch} {short}", kind, commit
+    return True, short, kind, commit
 
 
 def _update_source(source: Path, remote: str, branch: str) -> tuple[bool, str]:
-    """Move ``source`` to ``remote/branch`` without touching a dirty tree."""
+    """Move ``source`` to the ``branch`` pin without touching a dirty tree.
+
+    A branch pin fast-forwards. A **tag** pin is a fixed revision, so the checkout
+    is moved onto that commit *detached* - the only move that can go backwards (an
+    older tag, a rollback) as well as forwards. Neither path is ``reset --hard``,
+    a clean tree loses nothing because the commits stay in the refs, and a dirty
+    tree keeps the "mirror it as it stands" behaviour above.
+    """
     dirty = run_git(source, "status", "--porcelain").stdout.strip()
     if dirty:
         # Never clobber uncommitted work, but do not refuse to mirror either: the
@@ -8673,14 +10770,38 @@ def _update_source(source: Path, remote: str, branch: str) -> tuple[bool, str]:
             f"local changes ({dirty.splitlines()[0]}) - fast-forward skipped, "
             "mirroring this checkout as it stands"
         )
-    ok, detail = _fetch_source(source, remote, branch)
+    ok, detail, kind, commit = _fetch_source(source, remote, branch)
     if not ok:
         return False, detail
     head = run_git(source, "rev-parse", "--short", "HEAD").stdout.strip()
-    target = detail
+    target = run_git(source, "rev-parse", "--short", commit).stdout.strip()
+    if kind == "tag":
+        # A tag pin is a fixed revision, not a line of development, so the
+        # checkout has to sit on it rather than on a tracking branch. Detaching
+        # is the only move that can go backwards as well as forwards; the tree is
+        # clean here, so nothing is lost (the commits stay in the refs).
+        moved = run_git(source, "checkout", "--quiet", "--detach", commit)
+        if moved.returncode != 0:
+            tail = (moved.stderr or moved.stdout).strip().splitlines()
+            return False, f"cannot move {head} -> {detail}: {tail[-1] if tail else '?'}"
+        after = run_git(source, "rev-parse", "--short", "HEAD").stdout.strip()
+        if after == head:
+            return True, detail
+        return True, f"{head} -> {after} ({detail})"
+    label = f"{remote}/{branch} {detail}"
+    detached = run_git(source, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip() == "HEAD"
+    if detached:
+        # Leaving a tag pin for a branch: re-attach first, or the fast-forward
+        # would only move a detached HEAD and the branch pin would not stick.
+        reattach = run_git(source, "checkout", "--quiet", branch)
+        if reattach.returncode != 0:
+            tail = (reattach.stderr or reattach.stdout).strip().splitlines()
+            return False, (
+                f"cannot re-attach {branch} from the detached tag pin: {tail[-1] if tail else '?'}"
+            )
     if head == target:
-        return True, f"already at {remote}/{branch} {target}"
-    pulled = run_git(source, "merge", "--ff-only", f"{remote}/{branch}")
+        return True, f"already at {label}"
+    pulled = run_git(source, "merge", "--ff-only", commit)
     if pulled.returncode != 0:
         tail = (pulled.stderr or pulled.stdout).strip().splitlines()
         return False, f"cannot fast-forward {head} -> {target}: {tail[-1] if tail else '?'}"
@@ -8959,8 +11080,10 @@ def save_model_config(root: Path, config: dict) -> None:
 def resolved_model(root: Path, agent: str) -> dict:
     """The model the given instance should use: agent override, else role default."""
     config = load_model_config(root)
-    if agent in config["agents"]:
-        return dict(config["agents"][agent], source="agent")
+    wanted = pascal(agent)
+    for key, entry in config["agents"].items():
+        if pascal(key) == wanted:
+            return dict(entry, source="agent")
     role = resolve_role(agent) if agent else ""
     if role and role in config["roles"]:
         return dict(config["roles"][role], source="role")
@@ -9056,14 +11179,37 @@ def resolve_model_plan(root: Path, env=None) -> dict:
         env.get("PI_PROVIDER") or ""
     ).strip()
     assignments, missing = {}, []
+    alternate = (env.get("TEAMWORK_MODEL_ALT") or "").strip()
     for role in sorted(list_roles(root)):
         tier = LANE_TIER.get(role, "economy")
         model = strong if tier == "strong" else (economy or strong)
         if not model:
             missing.append(role)
             continue
-        assignments[role] = {"provider": provider, "model": model, "tier": tier}
+        lanes = instances_of(root, role)
+        if role in COORD_VERIFICATION_ROLES and len(lanes) > 1 and alternate:
+            # Two lanes that share weights, context and queue make the same
+            # mistake; independent verification needs a second model when one is
+            # available (references/Coordination.md).
+            for index, lane in enumerate(lanes):
+                assignments[lane] = {
+                    "provider": provider,
+                    "model": alternate if index % 2 else model,
+                    "tier": tier + ("-alt" if index % 2 else ""),
+                    "scope": "agent",
+                }
+        assignments[role] = {
+            "provider": provider,
+            "model": model,
+            "tier": tier,
+            "scope": "role",
+        }
     notes = [f"host: {host}"]
+    if len(instances_of(root, "reviewer")) > 1 and not alternate:
+        notes.append(
+            "reviewer lanes share one model: set TEAMWORK_MODEL_ALT to a second "
+            "model so `model auto --apply` decorrelates independent review"
+        )
     if missing:
         notes.append(
             "no model found in the environment for: "
@@ -9105,7 +11251,8 @@ def cmd_model_auto(args) -> int:
         die("nothing to apply: no model found in the environment")
     config = load_model_config(root)
     for role, entry in plan["assignments"].items():
-        config["roles"][role] = {"provider": entry["provider"], "model": entry["model"]}
+        target = config["agents"] if entry.get("scope") == "agent" else config["roles"]
+        target[role] = {"provider": entry["provider"], "model": entry["model"]}
     save_model_config(root, config)
     ledger_append(
         root,
@@ -9232,11 +11379,12 @@ def _parsers_workspace(sub, common) -> None:
     s = sub.add_parser(
         "consolidate",
         parents=[common],
-        help="promote stale short-term entries, evict long-term overflow",
+        help="promote stale short-term entries, evict long-term overflow (takes the role memory pen)",
     )
     s.add_argument("--agent")
     s.add_argument("--all", action="store_true")
     s.add_argument("--dry-run", action="store_true")
+    s.add_argument("--by", default="", help="which instance consolidates (default: the role)")
     s.set_defaults(func=cmd_consolidate)
 
     s = sub.add_parser("stats", parents=[common], help="memory sizes and cap violations")
@@ -9247,6 +11395,36 @@ def _parsers_workspace(sub, common) -> None:
     s = sub.add_parser("agents", parents=[common], help="list agent directories")
     s.set_defaults(func=cmd_agents)
 
+    s = sub.add_parser(
+        "instance",
+        parents=[common],
+        help="add/list/retire instances of ANY role (they share the role's memory)",
+    )
+    isub = s.add_subparsers(dest="instance_cmd", required=True)
+    p = isub.add_parser(
+        "add", parents=[common], help="launch one or more extra instances of a role"
+    )
+    p.add_argument("role", help="role slug to scale, e.g. architect, cto, designer")
+    p.add_argument("--count", type=int, default=1, help="how many instances to add (default 1)")
+    p.add_argument("--name", default="", help="explicit instance name instead of the next free one")
+    p.add_argument("--new-role", action="store_true", help="staff a role this team does not have")
+    p.add_argument("--by", default="ceo", help="who adds it (provenance)")
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.set_defaults(func=cmd_instance)
+    p = isub.add_parser(
+        "list", parents=[common], help="every role, its instances and memory writer"
+    )
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.set_defaults(func=cmd_instance)
+    p = isub.add_parser(
+        "retire", parents=[common], help="remove an idle instance (the role's memory stays)"
+    )
+    p.add_argument("name", help="instance to remove, e.g. reviewer-3")
+    p.add_argument("--by", default="ceo", help="who retires it (provenance)")
+    p.add_argument("--reason", default="", help="why it goes (required once it holds work)")
+    p.add_argument("--force", action="store_true", help="retire even while it holds work")
+    p.set_defaults(func=cmd_instance)
+
     # --- tasks ----------------------------------------------------------- #
     st = sub.add_parser("task", parents=[common], help="manage an agent's priority task list")
     tsub = st.add_subparsers(dest="task_cmd", required=True)
@@ -9264,6 +11442,13 @@ def _parsers_workspace(sub, common) -> None:
     s.add_argument("--deps", default="", help="comma list; cross-role as role:T-0001")
     s.add_argument("--shared", default="", help="shared board / issue / PR reference")
     s.add_argument("--tags", default="")
+    s.add_argument(
+        "--review-profile",
+        default="",
+        choices=["", "fast", "standard", "deep"],
+        dest="review_profile",
+        help="override the profile inferred from the diff (fast/standard/deep)",
+    )
     s.add_argument("--body", default="", help="acceptance criteria / notes")
     s.add_argument(
         "--bug",
@@ -9332,6 +11517,12 @@ def _parsers_workspace(sub, common) -> None:
     s.add_argument("handle")
     s.add_argument("--as", dest="by", required=True, help="instance taking it over")
     s.add_argument("--reason", required=True)
+    s.add_argument(
+        "--force",
+        default="",
+        metavar="REASON",
+        help="take over from a lane that still holds a live slot; reason required",
+    )
     s.set_defaults(func=cmd_task_reclaim)
 
     s = tsub.add_parser("rm", parents=[common], help="remove a task (own role only)")
@@ -9473,6 +11664,9 @@ def _parsers_memory(sub, common) -> None:
     s.add_argument("--importance", type=int, default=3)
     s.add_argument("--tags", default="")
     s.add_argument("--pin", action="store_true")
+    s.add_argument("--by", default="", help="who recorded it (provenance)")
+    s.add_argument("--src", default="", help="what it comes from (task, doc, run)")
+    s.add_argument("--rev", default="", help="revision it was verified at")
     s.set_defaults(func=cmd_global)
 
     s = sub.add_parser("recall", parents=[common], help="search memory")
@@ -9487,14 +11681,77 @@ def _parsers_memory(sub, common) -> None:
     s.add_argument("agent")
     s.add_argument("handle", help="M-0003 or key or substring")
     s.add_argument("--layer", choices=["short", "long"], default="short")
+    s.add_argument("--by", default="", help="which instance touches it (default: the agent)")
     s.set_defaults(func=cmd_touch)
 
     s = sub.add_parser("forget", parents=[common], help="delete an entry")
     s.add_argument("agent")
     s.add_argument("handle")
     s.add_argument("--layer", choices=["short", "long"], default="short")
+    s.add_argument("--by", default="", help="which instance forgets it (default: the agent)")
     s.set_defaults(func=cmd_forget)
 
+    # The role memory lease: exactly one instance revises a role's memory at a
+    # time, and it keeps the pen until the whole update is in.
+    s = sub.add_parser(
+        "memory",
+        parents=[common],
+        help="the role memory pen: claim/release/renew/contest/extend/revoke",
+    )
+    msub = s.add_subparsers(dest="memory_cmd", required=True)
+    p = msub.add_parser(
+        "claim", parents=[common], help="hold the pen for the role's memory until you release it"
+    )
+    p.add_argument("agent", help="role (or instance) whose memory you will revise")
+    p.add_argument("--by", default="", help="the instance taking the pen (required by the lease)")
+    p.add_argument("--ttl", type=int, default=0, help="lease minutes (default MemoryLeaseMinutes)")
+    p.add_argument("--reason", default="", help="what update you are about to make")
+    p.add_argument(
+        "--force",
+        default="",
+        metavar="REASON",
+        help="take the pen from a stalled holder; reason required and recorded",
+    )
+    p.set_defaults(func=cmd_memory)
+    p = msub.add_parser("release", parents=[common], help="give the pen back (holder only)")
+    p.add_argument("agent")
+    p.add_argument("--by", default="", help="the instance releasing it")
+    p.add_argument("--force", default="", metavar="REASON", help="release a dead lane's pen")
+    p.set_defaults(func=cmd_memory)
+    p = msub.add_parser("renew", parents=[common], help="extend the lease while the update runs")
+    p.add_argument("agent")
+    p.add_argument("--by", default="", help="the holder")
+    p.add_argument("--ttl", type=int, default=0, help="lease minutes (default MemoryLeaseMinutes)")
+    p.set_defaults(func=cmd_memory)
+    p = msub.add_parser(
+        "contest",
+        parents=[common],
+        help="peer: ask the CTO to rule on a lease that is running unusually long",
+    )
+    p.add_argument("agent", help="role whose memory is held")
+    p.add_argument("--by", default="", help="the peer instance raising it")
+    p.add_argument("--reason", default="", help="why the update looks stalled (required)")
+    p.set_defaults(func=cmd_memory)
+    p = msub.add_parser(
+        "extend", parents=[common], help="CTO/CEO: rule that the holder keeps the pen longer"
+    )
+    p.add_argument("agent")
+    p.add_argument("--by", default="", help="the arbiter ruling")
+    p.add_argument("--ttl", type=int, default=0, help="extra minutes (default: a full lease)")
+    p.add_argument("--reason", default="", help="why more time is fair (required)")
+    p.set_defaults(func=cmd_memory)
+    p = msub.add_parser(
+        "revoke", parents=[common], help="CTO/CEO: remove the lease and free the role now"
+    )
+    p.add_argument("agent")
+    p.add_argument("--by", default="", help="the arbiter ruling")
+    p.add_argument("--reason", default="", help="why the pen is removed (required)")
+    p.set_defaults(func=cmd_memory)
+    p = msub.add_parser("status", parents=[common], help="who may revise which role's memory now")
+    p.add_argument("agent", nargs="?", default="", help="one role (default: every role)")
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.set_defaults(func=cmd_memory)
+
 
 def _parsers_task(sub, common) -> None:
     """`task` command surface."""
@@ -9521,6 +11778,12 @@ def _parsers_quality(sub, common) -> None:
     s.add_argument(
         "--release", action="store_true", help="hand a claimed deliverable back to the queue"
     )
+    s.add_argument("--renew", action="store_true", help="extend the lease on a claim you hold")
+    s.add_argument(
+        "--packet",
+        action="store_true",
+        help="print the review packet (profile, diff, gates, checklist) instead of a verdict",
+    )
     s.add_argument("--by", default="reviewer")
     s.add_argument("--result", choices=["pass", "fail"])
     s.add_argument("--evidence", default="", help="verification command @rev -> result")
@@ -9779,6 +12042,11 @@ def _parsers_integration(sub, common) -> None:
         action="store_true",
         help="also fail commits authored outside the team identity domain",
     )
+    s.add_argument(
+        "--guard-committer",
+        action="store_true",
+        help="fail when a commit carries a committer outside the team identity domain",
+    )
     s.set_defaults(func=cmd_identity)
 
     s = sub.add_parser(
@@ -9813,11 +12081,17 @@ def _parsers_integration(sub, common) -> None:
     s.add_argument(
         "--lfs-threshold",
         type=int,
-        default=1_000_000,
+        default=LFS_MAX_BYTES,
         help="bytes above which a file must be LFS-tracked",
     )
     s.set_defaults(func=cmd_commit)
 
+    # `hooks` installs and inspects the git hooks; `hook` is what those hooks call
+    # back into. The rules act on the commit/push flow, so they register here.
+    from .hooks import add_parsers as _add_hook_parsers
+
+    _add_hook_parsers(sub, common)
+
 
 def _parsers_governance(sub, common) -> None:
     """`governance` command surface."""
@@ -9912,6 +12186,20 @@ def _parsers_governance(sub, common) -> None:
 
 def _parsers_audit(sub, common) -> None:
     """`audit` command surface."""
+    s = sub.add_parser(
+        "coordination",
+        parents=[common],
+        help="coordination health: conformity, rubber-stamping, turf, merge rate",
+    )
+    s.add_argument("--json", action="store_true", help="machine-readable report")
+    s.add_argument(
+        "--strict",
+        action="store_true",
+        help="exit 1 when a high-severity finding is open (default: report only)",
+    )
+    s.add_argument("--commit", action="store_true", help="append the result to the ledger")
+    s.set_defaults(func=cmd_coordination)
+
     s = sub.add_parser(
         "links", parents=[common], help="check markdown cross-links, URLs and back-links"
     )
@@ -10097,6 +12385,12 @@ def _parsers_meta(sub, common) -> None:
     p.add_argument("--json", action="store_true", help="machine-readable output")
     p.set_defaults(func=cmd_imaging)
 
+    # The harness surface registry and its lint live in their own module: they
+    # measure the tree at run time and must not grow this command layer.
+    from .harness import add_parsers as _add_harness_parsers
+
+    _add_harness_parsers(sub, common)
+
 
 def main(argv=None) -> int:
     args = build_parser().parse_args(argv)