@arbiterforge/ca-pi 0.10.8 → 0.10.11

package/README.md

@@ -10,7 +10,7 @@ project context. You decide. codeArbiter enforces.
 <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-d97757">
 <img alt="Codex plugin" src="https://img.shields.io/badge/OpenAI_Codex-plugin-10a37f">
 <img alt="Pi Feature Forge preview" src="https://img.shields.io/badge/ca--pi-Feature_Forge_preview-d97757">
-<img alt="version 2.17.7" src="https://img.shields.io/badge/version-2.17.7-2b7489">
+<img alt="version 2.17.10" src="https://img.shields.io/badge/version-2.17.10-2b7489">
 <img alt="core lanes" src="https://img.shields.io/badge/core_lanes-18-555">
 <img alt="skills" src="https://img.shields.io/badge/skills-23-555">
 <img alt="agents" src="https://img.shields.io/badge/agents-19-555">
@@ -117,7 +117,7 @@ Approve the normal plugin trust prompt, open the target repository, and continue
 
 ### Codex CLI
 
-The public GitHub-slug flow is **available now**. The repository currently ships `ca-codex 0.9.7`;
+The public GitHub-slug flow is **available now**. The repository currently ships `ca-codex 0.9.10`;
 the dated end-to-end public-install record discovered `ca-codex 0.2.4` from release `v2.8.13`.
 Current packaging and shared-core parity are continuously verified, while that dated live-install
 record stays labeled rather than being silently promoted to evidence for a newer adapter:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.10.8",
+  "version": "0.10.11",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `ca-pi` are documented in this file.
 
 ## [Unreleased]
 
+## [0.10.11] - 2026-09-08
+
+### Fixed
+
+- Resolve genuine append-only audit-log conflicts through a fail-closed helper that preserves both branch histories and records the immediate H-05 authorization, with shared audit-path locks and a locked mandatory-override writer preventing concurrent row loss.
+
+## [0.10.10] - 2026-09-07
+
+### Fixed
+
+- Use the same documented done-tasks template for initialization and first-use archiving, with byte-identical UTF-8 headers on Windows and POSIX.
+
+## [0.10.9] - 2026-09-06
+
+### Fixed
+
+- Keep task-board lifecycles Git-clean by locally excluding the retained OS-lock sidecar during initialization, with an explicit repair option for existing repositories.
+
 ## [0.10.8] - 2026-09-06
 
 ### Fixed

package/plugins/ca-pi/hooks/_appendonlyconflictlib.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+# codeArbiter - fail-closed resolution of genuine H-05 append-only conflicts.
+#
+# The public entry point is resolve-append-only-conflict.py.  This module keeps
+# Git inspection, byte validation, deterministic union construction, atomic
+# replacement, and explicit staging testable and host-neutral.
+#
+# Public API:
+#   resolve(target, reason, cwd=None) -> str  resolve and return repo-relative path
+#   main(argv=None) -> int                    CLI contract
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import os
+from pathlib import Path
+import stat
+import subprocess
+import sys
+import tempfile
+
+from _hooklib import acquire_lock, audit_lock_key, release_lock
+from _gitexec import git_executable
+from _protectedlib import classify_protected
+
+
+BOM = b"\xef\xbb\xbf"
+MAX_REASON = 500
+SUPPORTED_AUDIT_PATHS = frozenset(
+    {".codearbiter/overrides.log", ".codearbiter/gate-events.log"}
+)
+
+
+class ResolutionError(RuntimeError):
+    """A surfaced, non-mutating refusal of the conflict-resolution contract."""
+
+
+class ConcurrentAppendError(ResolutionError):
+    """A displaced original inode changed and was restored before refusal."""
+
+    def __init__(self, path, restored, observed=None):
+        super().__init__(f"concurrent append detected while replacing '{Path(path).name}'")
+        self.path = Path(path)
+        self.restored = restored
+        self.observed = observed
+
+
+def _git(cwd, *args, input_bytes=None, check=True):
+    try:
+        result = subprocess.run(
+            [git_executable(), *args],
+            cwd=cwd,
+            input=input_bytes,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+    except OSError as error:
+        raise ResolutionError(f"git unavailable: {error}") from error
+    if check and result.returncode != 0:
+        detail = result.stderr.decode("utf-8", errors="replace").strip()
+        raise ResolutionError(f"git {' '.join(args)} failed: {detail or 'unknown error'}")
+    return result
+
+
+def _repository_root(cwd):
+    result = _git(cwd, "rev-parse", "--show-toplevel")
+    try:
+        raw = result.stdout.decode("utf-8", errors="strict").strip()
+    except UnicodeDecodeError as error:
+        raise ResolutionError("git returned an invalid UTF-8 repository root") from error
+    if not raw:
+        raise ResolutionError("git returned an empty repository root")
+    return Path(raw).resolve()
+
+
+def _relative_target(root, target):
+    candidate = Path(target)
+    if candidate.is_absolute():
+        raise ResolutionError("target must be a repository-relative supported append-only path")
+    normalized = Path(os.path.normpath(str(candidate)))
+    if normalized == Path(".") or ".." in normalized.parts:
+        raise ResolutionError("target must be a contained supported append-only path")
+    path = root / normalized
+    try:
+        resolved_root = os.path.realpath(root)
+        resolved_path = os.path.realpath(path)
+        common = os.path.commonpath((resolved_root, resolved_path))
+    except ValueError as error:
+        raise ResolutionError("target escapes the repository root") from error
+    if os.path.normcase(common) != os.path.normcase(resolved_root):
+        raise ResolutionError("target escapes the repository root")
+    relative = normalized.as_posix()
+    if relative not in SUPPORTED_AUDIT_PATHS or "audit" not in classify_protected(
+        str(path), str(root)
+    ):
+        raise ResolutionError(f"'{relative}' is not a supported append-only H-05 path")
+    try:
+        mode = path.lstat().st_mode
+    except OSError as error:
+        raise ResolutionError(f"cannot inspect '{relative}': {error}") from error
+    if not stat.S_ISREG(mode) or path.is_symlink():
+        raise ResolutionError(f"'{relative}' is not a regular non-link file")
+    return relative, path
+
+
+def _validate_bytes(label, raw):
+    if BOM in raw:
+        raise ResolutionError(f"{label} contains a UTF-8 BOM")
+    if b"\x00" in raw:
+        raise ResolutionError(f"{label} contains a NUL byte")
+    if b"\r" in raw:
+        raise ResolutionError(f"{label} is not canonical LF text")
+    try:
+        raw.decode("utf-8", errors="strict")
+    except UnicodeDecodeError as error:
+        raise ResolutionError(f"{label} is not valid UTF-8") from error
+    if raw and not raw.endswith(b"\n"):
+        raise ResolutionError(f"{label} does not end with LF")
+
+
+def _marker_run(line, marker):
+    if not line.endswith(b"\n"):
+        return 0
+    body = line[:-1]
+    size = 0
+    while size < len(body) and body[size : size + 1] == marker:
+        size += 1
+    if size < 7 or (len(body) > size and body[size : size + 1] != b" "):
+        return 0
+    return size
+
+
+def _validate_conflicted_worktree(raw, base, ours_suffix, theirs_suffix):
+    """Prove the worktree is only Git's rendering of the three index stages."""
+    # Git for Windows may render conflict markers and checked-out blob lines as
+    # CRLF even though every index blob is canonical LF. Normalize only complete
+    # CRLF pairs for comparison; lone CR remains invalid and the original bytes
+    # stay untouched for rollback.
+    normalized = raw.replace(b"\r\n", b"\n")
+    _validate_bytes("conflicted worktree", normalized)
+    if not normalized.startswith(base):
+        raise ResolutionError("conflicted worktree does not preserve the merge-base prefix")
+    lines = normalized[len(base) :].splitlines(keepends=True)
+    starts = [(index, _marker_run(line, b"<")) for index, line in enumerate(lines)]
+    starts = [(index, size) for index, size in starts if size]
+    if len(starts) != 1:
+        raise ResolutionError("conflicted worktree is not one recognized Git conflict rendering")
+    start, marker_size = starts[0]
+    separator_line = (b"=" * marker_size) + b"\n"
+    separators = [index for index, line in enumerate(lines) if line == separator_line]
+    ends = [
+        index
+        for index, line in enumerate(lines)
+        if _marker_run(line, b">") == marker_size
+    ]
+    base_markers = [
+        index
+        for index, line in enumerate(lines)
+        if _marker_run(line, b"|") == marker_size
+    ]
+    if len(separators) != 1 or len(ends) != 1 or len(base_markers) > 1:
+        raise ResolutionError("conflicted worktree has ambiguous Git conflict markers")
+    separator = separators[0]
+    end = ends[0]
+    base_marker = base_markers[0] if base_markers else None
+    ours_end = base_marker if base_marker is not None else separator
+    if not (start < ours_end <= separator < end):
+        raise ResolutionError("conflicted worktree has out-of-order Git conflict markers")
+    if base_marker is not None and b"".join(lines[base_marker + 1 : separator]):
+        raise ResolutionError("conflicted worktree has unexpected merge-base conflict bytes")
+
+    common_prefix = b"".join(lines[:start])
+    ours_body = b"".join(lines[start + 1 : ours_end])
+    theirs_body = b"".join(lines[separator + 1 : end])
+    common_suffix = b"".join(lines[end + 1 :])
+    if ours_suffix != common_prefix + ours_body + common_suffix:
+        raise ResolutionError("conflicted worktree differs from the current-branch index stage")
+    if theirs_suffix != common_prefix + theirs_body + common_suffix:
+        raise ResolutionError("conflicted worktree differs from the incoming-branch index stage")
+
+
+def _unmerged(root, relative, *, allow_resolved=False):
+    result = _git(root, "ls-files", "-u", "-z", "--", relative)
+    records = []
+    for item in result.stdout.split(b"\0"):
+        if not item:
+            continue
+        try:
+            metadata, encoded_path = item.split(b"\t", 1)
+            mode, oid, stage = metadata.decode("ascii").split(" ")
+            path = encoded_path.decode("utf-8", errors="strict")
+            records.append((mode, oid, int(stage), path))
+        except (ValueError, UnicodeDecodeError) as error:
+            raise ResolutionError("malformed unmerged index record") from error
+    if allow_resolved and not records:
+        return []
+    if len(records) != 3 or [record[2] for record in records] != [1, 2, 3]:
+        raise ResolutionError("target is not in a complete three-stage conflict")
+    if any(record[3] != relative for record in records):
+        raise ResolutionError("unmerged index path does not match the requested target")
+    if any(record[0] != "100644" for record in records):
+        raise ResolutionError("append-only conflict stages must all be regular 100644 blobs")
+    return records
+
+
+def _tracked_index(root, relative):
+    result = _git(root, "ls-files", "--stage", "-z", "--", relative)
+    records = []
+    for item in result.stdout.split(b"\0"):
+        if not item:
+            continue
+        try:
+            metadata, encoded_path = item.split(b"\t", 1)
+            mode, oid, stage = metadata.decode("ascii").split(" ")
+            path = encoded_path.decode("utf-8", errors="strict")
+            records.append((mode, oid, int(stage), path))
+        except (ValueError, UnicodeDecodeError) as error:
+            raise ResolutionError("malformed tracked index record") from error
+    return records
+
+
+def _blob(root, oid, label):
+    result = _git(root, "cat-file", "blob", oid)
+    raw = result.stdout
+    _validate_bytes(label, raw)
+    return raw
+
+
+def _authorization(root, reason):
+    reason = reason.strip()
+    if not reason:
+        raise ResolutionError("--reason must contain a non-empty reason")
+    if len(reason) > MAX_REASON or "|" in reason or "\n" in reason or "\r" in reason:
+        raise ResolutionError("--reason must be at most 500 characters with no pipes or newlines")
+    result = _git(root, "config", "--get", "user.email", check=False)
+    if result.returncode != 0:
+        raise ResolutionError("git config user.email is required for the attributed override")
+    try:
+        identity = result.stdout.decode("utf-8", errors="strict").strip()
+    except UnicodeDecodeError as error:
+        raise ResolutionError("git config user.email is not valid UTF-8") from error
+    if not identity or len(identity) > 254 or "|" in identity or "\n" in identity or "\r" in identity:
+        raise ResolutionError("git config user.email is not a valid override identity")
+    timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+    return f"[{timestamp}] | BY: {identity} | GATE: H-05 | REASON: {reason}\n".encode("utf-8")
+
+
+def _append_parts(root, records):
+    base = _blob(root, records[0][1], "merge base")
+    ours = _blob(root, records[1][1], "current branch")
+    theirs = _blob(root, records[2][1], "incoming branch")
+    if not ours.startswith(base):
+        raise ResolutionError("current branch is not append-only relative to the merge base")
+    if not theirs.startswith(base):
+        raise ResolutionError("incoming branch is not append-only relative to the merge base")
+    ours_suffix = ours[len(base) :]
+    theirs_suffix = theirs[len(base) :]
+    if not ours_suffix or not theirs_suffix:
+        raise ResolutionError("both conflict sides must append non-empty history")
+    return base, ours_suffix, theirs_suffix
+
+
+def _build_union(root, records):
+    base, ours_suffix, theirs_suffix = _append_parts(root, records)
+    merged = base + ours_suffix + theirs_suffix
+    _validate_bytes("resolved output", merged)
+    return merged
+
+
+def _sync_parent(path):
+    if os.name == "nt":
+        return False
+    flags = os.O_RDONLY
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    parent_fd = os.open(path.parent, flags)
+    try:
+        os.fsync(parent_fd)
+    finally:
+        os.close(parent_fd)
+    return True
+
+
+def _write_bytes_atomic(path, raw, *, expected=None):
+    original_mode = stat.S_IMODE(path.stat().st_mode)
+    fd, temporary = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+    witness = None
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(raw)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temporary, original_mode)
+        if expected is not None:
+            witness_fd, witness = tempfile.mkstemp(
+                dir=path.parent, prefix=path.name + ".", suffix=".witness"
+            )
+            os.close(witness_fd)
+            os.remove(witness)
+            os.link(path, witness)
+            observed = Path(witness).read_bytes()
+            if observed != expected:
+                raise ConcurrentAppendError(path, restored=True, observed=observed)
+        os.replace(temporary, path)
+        temporary = None
+        _sync_parent(path)
+        if witness is not None:
+            displaced = Path(witness).read_bytes()
+            if displaced != expected:
+                restored = False
+                try:
+                    os.replace(witness, path)
+                    witness = None
+                    _sync_parent(path)
+                    restored = True
+                finally:
+                    raise ConcurrentAppendError(path, restored=restored, observed=displaced)
+            os.remove(witness)
+            witness = None
+    except Exception:
+        if temporary is not None:
+            try:
+                os.remove(temporary)
+            except OSError:
+                pass
+        if witness is not None:
+            try:
+                os.remove(witness)
+            except OSError:
+                pass
+        raise
+
+
+def _restore_index(root, relative, records):
+    removed = _git(root, "update-index", "--force-remove", "--", relative, check=False)
+    if removed.returncode != 0:
+        detail = removed.stderr.decode("utf-8", errors="replace").strip()
+        raise ResolutionError(f"could not clear staged resolution during rollback: {detail}")
+    index_info = b"".join(
+        f"{mode} {oid} {stage}\t{path}\n".encode("utf-8")
+        for mode, oid, stage, path in records
+    )
+    _git(root, "update-index", "--index-info", input_bytes=index_info)
+
+
+def resolve(target, reason, cwd=None):
+    root = _repository_root(cwd or os.getcwd())
+    relative, path = _relative_target(root, target)
+    records = _unmerged(root, relative)
+    authorization = _authorization(root, reason)
+    base, ours_suffix, theirs_suffix = _append_parts(root, records)
+    proposed = base + ours_suffix + theirs_suffix
+    _validate_bytes("resolved output", proposed)
+    changes = {relative: proposed}
+    paths = {relative: path}
+    originals = {relative: path.read_bytes()}
+    _validate_conflicted_worktree(originals[relative], base, ours_suffix, theirs_suffix)
+    index_records = {relative: records}
+    override_relative = ".codearbiter/overrides.log"
+    if relative == override_relative:
+        changes[relative] += authorization
+    else:
+        override_relative, override_path = _relative_target(root, override_relative)
+        if _unmerged(root, override_relative, allow_resolved=True):
+            raise ResolutionError("the override audit sink is itself unmerged")
+        for diff_args in (("diff", "--quiet"), ("diff", "--cached", "--quiet")):
+            clean = _git(root, *diff_args, "--", override_relative, check=False)
+            if clean.returncode != 0:
+                raise ResolutionError("the override audit sink must be clean before resolution")
+        override_raw = override_path.read_bytes()
+        _validate_bytes("override audit sink", override_raw)
+        changes[override_relative] = override_raw + authorization
+        paths[override_relative] = override_path
+        originals[override_relative] = override_raw
+        index_records[override_relative] = _tracked_index(root, override_relative)
+    try:
+        common_raw = _git(root, "rev-parse", "--git-common-dir").stdout.decode(
+            "utf-8", errors="strict"
+        ).strip()
+    except UnicodeDecodeError as error:
+        raise ResolutionError("git returned an invalid UTF-8 common directory") from error
+    if not common_raw:
+        raise ResolutionError("git returned an empty common directory")
+    common = Path(common_raw)
+    if not common.is_absolute():
+        common = root / common
+    lock = acquire_lock(str(common.resolve() / "codearbiter-append-only-conflict"))
+    if lock is None:
+        raise ResolutionError("another append-only conflict resolution holds the repository lock")
+    path_locks = []
+    try:
+        for changed_relative in sorted(changes):
+            path_lock = acquire_lock(audit_lock_key(root, paths[changed_relative]))
+            if path_lock is None:
+                raise ResolutionError(
+                    f"another writer holds the audit path lock for '{changed_relative}'"
+                )
+            path_locks.append(path_lock)
+        if _unmerged(root, relative) != records or path.read_bytes() != originals[relative]:
+            raise ResolutionError("conflict state changed during validation; retry from fresh evidence")
+        try:
+            for changed_relative, raw in changes.items():
+                if paths[changed_relative].read_bytes() != originals[changed_relative]:
+                    raise ResolutionError("protected state changed during validation; retry")
+                _write_bytes_atomic(
+                    paths[changed_relative], raw, expected=originals[changed_relative]
+                )
+            staged = _git(root, "add", "--", *changes.keys(), check=False)
+            if staged.returncode != 0:
+                detail = staged.stderr.decode("utf-8", errors="replace").strip()
+                raise ResolutionError(f"git add failed: {detail or 'unknown error'}")
+            if _unmerged(root, relative, allow_resolved=True):
+                raise ResolutionError("git add did not clear the three-stage conflict")
+            for changed_relative, raw in changes.items():
+                index_blob = _git(root, "show", f":0:{changed_relative}").stdout
+                if index_blob != raw:
+                    raise ResolutionError(
+                        f"staged blob does not match validated output for {changed_relative}"
+                    )
+        except Exception as error:
+            # The replacement is atomic; if staging or verification fails, put
+            # the exact conflict-marker worktree bytes and three index stages
+            # back.  This also covers a successful `git add` followed by a
+            # failed staged-blob verification.
+            for changed_relative, raw in originals.items():
+                if isinstance(error, ConcurrentAppendError) and paths[changed_relative] == error.path:
+                    if error.restored:
+                        continue
+                    if error.observed is not None:
+                        raw = error.observed
+                _write_bytes_atomic(paths[changed_relative], raw)
+            for changed_relative, prior_records in index_records.items():
+                _restore_index(root, changed_relative, prior_records)
+            raise
+    finally:
+        for path_lock in reversed(path_locks):
+            release_lock(path_lock)
+        release_lock(lock)
+    return relative
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Resolve one genuine H-05 append-only Git conflict without weakening the guard."
+    )
+    parser.add_argument("target", help="repository-relative protected append-only path")
+    parser.add_argument("--reason", required=True, help="specific immediate H-05 override reason")
+    args = parser.parse_args(argv)
+    try:
+        relative = resolve(args.target, args.reason)
+    except (OSError, ResolutionError) as error:
+        print(f"append-only conflict resolution refused: {error}", file=sys.stderr)
+        return 1
+    print(f"resolved and staged append-only conflict: {relative}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/ca-pi/hooks/_hooklib.py

@@ -96,6 +96,7 @@
 #                                         non-blocking + bounded LOCK_WAIT retry spin,
 #                                         fail-soft None on contention/timeout/OSError
 #   release_lock(handle) -> None          release + close; None handle is a no-op
+#   audit_lock_key(root, path) -> str     trusted Git-owned key for an audit path
 #   block(tag, msg) -> None              BLOCK tool call: print to stderr and exit 2
 #   remind(tag, msg) -> None             non-blocking nudge to stderr
 #   warn(msg) -> None                    loud degradation breadcrumb to stderr
@@ -105,6 +106,7 @@
 
 import datetime
 import errno
+import hashlib
 import json
 import os
 import re
@@ -216,8 +218,10 @@ from _sensitivelib import (  # noqa: F401
 )
 
 
-# Serialize same-process Windows writers before taking the cross-process lock.
-_GATE_EVENTS_WINDOWS_LOCK = threading.Lock()
+# Serialize same-process writers before taking the bounded cross-process lock.
+# POSIX flock and Windows byte-range locks are process-scoped, so sibling
+# threads can otherwise burn the shared wait budget contending with each other.
+_GATE_EVENTS_PROCESS_LOCK = threading.Lock()
 _WINDOWS_LOCK_TIMEOUT_SECONDS = 5.0
 _WINDOWS_LOCK_RETRY_SECONDS = 0.01
 _WINDOWS_CRT_EDEADLK = 36
@@ -409,6 +413,63 @@ def release_lock(handle):
             pass
 
 
+def audit_lock_key(root, path):
+    """Return a deterministic audit lock key beneath Git-owned metadata.
+
+    Audit paths and their siblings are repository-controlled, so an adjacent
+    lock can be a checked-out symlink that redirects acquire_lock's seed byte
+    outside the checkout. Linked worktrees resolve to their common Git
+    directory and therefore share one trusted key per repository-relative path.
+    """
+    root = os.path.abspath(os.fspath(root))
+    path = os.path.abspath(os.fspath(path))
+    try:
+        if os.path.normcase(os.path.commonpath((root, path))) != os.path.normcase(root):
+            raise ValueError
+    except (OSError, ValueError) as error:
+        raise OSError("audit lock target is outside the repository root") from error
+
+    dotgit = os.path.join(root, ".git")
+    if os.path.isdir(dotgit):
+        common = dotgit
+    elif os.path.isfile(dotgit):
+        try:
+            with open(dotgit, encoding="utf-8") as handle:
+                pointer = handle.read(4097)
+        except OSError as error:
+            raise OSError("cannot read linked-worktree Git metadata") from error
+        if len(pointer) > 4096 or not pointer.startswith("gitdir:"):
+            raise OSError("linked-worktree Git metadata is malformed")
+        gitdir = pointer[7:].strip()
+        if not gitdir:
+            raise OSError("linked-worktree Git directory is empty")
+        if not os.path.isabs(gitdir):
+            gitdir = os.path.join(root, gitdir)
+        commondir_file = os.path.join(gitdir, "commondir")
+        if os.path.isfile(commondir_file):
+            try:
+                with open(commondir_file, encoding="utf-8") as handle:
+                    relative_common = handle.read(4097).strip()
+            except OSError as error:
+                raise OSError("cannot read Git common-directory metadata") from error
+            if not relative_common or len(relative_common) > 4096:
+                raise OSError("Git common-directory metadata is malformed")
+            common = relative_common if os.path.isabs(relative_common) else os.path.join(
+                gitdir, relative_common
+            )
+        else:
+            common = gitdir
+    else:
+        raise OSError("repository Git metadata is unavailable for audit locking")
+
+    common = os.path.realpath(common)
+    if not os.path.isdir(common):
+        raise OSError("Git common directory is unavailable for audit locking")
+    relative = os.path.relpath(path, root).replace("\\", "/")
+    digest = hashlib.sha256(relative.encode("utf-8")).hexdigest()
+    return os.path.join(common, "codearbiter-audit-locks", digest)
+
+
 # The H-11 authoring-marker freshness window (issue #567) — the single
 # declaration every `marker_fresh(marker, minutes)` call site resolves by
 # import. Previously five independent `30` literals (pre-write.py,
@@ -469,17 +530,27 @@ def _log_gate_event(kind, tag, msg):
             host = "unknown"
         tag_part = f"[{tag}] " if tag else ""
         line = f"[{ts}] {kind} {tag_part}host={host} hook={hook} | {msg}\n"
+        log_path = os.path.join(cad, "gate-events.log")
         flags = os.O_APPEND | os.O_CREAT | os.O_WRONLY
         if hasattr(os, "O_BINARY"):
             flags |= os.O_BINARY
         process_lock_acquired = False
-        if os.name == "nt":
-            _GATE_EVENTS_WINDOWS_LOCK.acquire()
+        try:
+            _GATE_EVENTS_PROCESS_LOCK.acquire()
             process_lock_acquired = True
+            audit_lock = acquire_lock(audit_lock_key(root, log_path))
+        except Exception:
+            if process_lock_acquired:
+                _GATE_EVENTS_PROCESS_LOCK.release()
+            raise
+        if audit_lock is None:
+            if process_lock_acquired:
+                _GATE_EVENTS_PROCESS_LOCK.release()
+            return
         fd = None
         os_lock_acquired = False
         try:
-            fd = os.open(os.path.join(cad, "gate-events.log"), flags, 0o600)
+            fd = os.open(log_path, flags, 0o600)
             if os.name == "nt":
                 import msvcrt
                 os.lseek(fd, 0, os.SEEK_SET)
@@ -504,10 +575,15 @@ def _log_gate_event(kind, tag, msg):
                     msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
                 except Exception:  # noqa: BLE001 — outer sink remains fail-open
                     pass
-            if process_lock_acquired:
-                _GATE_EVENTS_WINDOWS_LOCK.release()
-            if fd is not None:
-                os.close(fd)
+            try:
+                if fd is not None:
+                    os.close(fd)
+            finally:
+                try:
+                    release_lock(audit_lock)
+                finally:
+                    if process_lock_acquired:
+                        _GATE_EVENTS_PROCESS_LOCK.release()
     except Exception:  # noqa: BLE001 — fail-open: the sink must never affect the gate
         pass
 

package/plugins/ca-pi/hooks/_host.py

@@ -11,7 +11,7 @@ import hostapi  # noqa: E402
 class PiHost(hostapi.Host):
     name = "pi"
     adapter_name = "@arbiterforge/ca-pi"
-    adapter_version = "0.10.8"
+    adapter_version = "0.10.11"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

package/plugins/ca-pi/hooks/_modelib.py

@@ -25,7 +25,7 @@ import os
 import re
 
 from _activationlib import marker_root
-from _hooklib import write_text_atomic
+from _hooklib import acquire_lock, audit_lock_key, release_lock, write_text_atomic
 
 
 # ---------------------------------------------------------------------------
@@ -645,12 +645,21 @@ def _overrides_has_line(root, line):
 
 def _append_override_line(root, line):
     """Append one audit line to overrides.log. True on a confirmed write."""
+    lock = None
     try:
-        with open(_overrides_log_path(root), "a", encoding="utf-8") as f:
+        path = _overrides_log_path(root)
+        lock = acquire_lock(audit_lock_key(root, path))
+        if lock is None:
+            return False
+        with open(path, "a", encoding="utf-8") as f:
             f.write(line)
+            f.flush()
+            os.fsync(f.fileno())
         return True
-    except OSError:
+    except Exception:  # noqa: BLE001 — mode audit settlement remains fail-soft
         return False
+    finally:
+        release_lock(lock)
 
 
 def _dev_dropped_close_note(count, host_name=None):

package/plugins/ca-pi/hooks/_overrideappendlib.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Fail-closed, cooperatively locked append for mandatory override records."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+
+from _gitexec import git_executable
+from _hooklib import acquire_lock, audit_lock_key, release_lock
+
+
+MAX_FIELD = 500
+GATE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+
+
+class OverrideAppendError(RuntimeError):
+    """The mandatory audit row could not be safely and durably appended."""
+
+
+def _git(cwd, *args):
+    try:
+        result = subprocess.run(
+            [git_executable(), *args], cwd=cwd, stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE, check=False,
+        )
+    except OSError as error:
+        raise OverrideAppendError(f"git unavailable: {error}") from error
+    if result.returncode != 0:
+        detail = result.stderr.decode("utf-8", errors="replace").strip()
+        raise OverrideAppendError(f"git {' '.join(args)} failed: {detail or 'unknown error'}")
+    return result.stdout
+
+
+def _root(cwd):
+    try:
+        raw = _git(cwd, "rev-parse", "--show-toplevel").decode("utf-8", errors="strict").strip()
+    except UnicodeDecodeError as error:
+        raise OverrideAppendError("git returned an invalid UTF-8 repository root") from error
+    if not raw:
+        raise OverrideAppendError("git returned an empty repository root")
+    return Path(raw).resolve()
+
+
+def _field(label, value):
+    if not value or len(value) > MAX_FIELD or any(char in value for char in "|\r\n"):
+        raise OverrideAppendError(
+            f"{label} must be non-empty, at most {MAX_FIELD} characters, and contain no pipe or newline"
+        )
+    return value
+
+
+def _identity(root):
+    try:
+        value = _git(root, "config", "user.email").decode("utf-8", errors="strict").strip()
+    except UnicodeDecodeError as error:
+        raise OverrideAppendError("git config user.email is not valid UTF-8") from error
+    _field("git config user.email", value)
+    if len(value) > 254 or any(char.isspace() for char in value):
+        raise OverrideAppendError("git config user.email is not a valid override identity")
+    return value
+
+
+def _validate_file_type(path):
+    try:
+        mode = path.lstat().st_mode
+    except OSError as error:
+        raise OverrideAppendError(f"cannot inspect overrides.log: {error}") from error
+    if not stat.S_ISREG(mode) or path.is_symlink():
+        raise OverrideAppendError("overrides.log is not a regular non-link file")
+
+
+def _validate_existing(path, raw):
+    _validate_file_type(path)
+    if raw.startswith(b"\xef\xbb\xbf") or b"\x00" in raw or b"\r" in raw:
+        raise OverrideAppendError("overrides.log is not canonical UTF-8 LF text")
+    try:
+        raw.decode("utf-8", errors="strict")
+    except UnicodeDecodeError as error:
+        raise OverrideAppendError("overrides.log is not valid UTF-8") from error
+    if raw and not raw.endswith(b"\n"):
+        raise OverrideAppendError("overrides.log does not end with LF")
+
+
+def append_override(*, gate=None, security_finding=None, reason, cwd=None):
+    root = _root(cwd or os.getcwd())
+    path = root / ".codearbiter" / "overrides.log"
+    _validate_file_type(path)
+    before = path.read_bytes()
+    _validate_existing(path, before)
+    identity = _identity(root)
+    reason = _field("reason", reason)
+    timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+    if gate is not None:
+        if not GATE_RE.fullmatch(gate):
+            raise OverrideAppendError("gate must be a compact gate identifier")
+        body = f"GATE: {gate}"
+    else:
+        body = f"SECURITY-OVERRIDE | FINDING: {_field('security finding', security_finding)}"
+    line = f"[{timestamp}] | BY: {identity} | {body} | REASON: {reason}\n".encode("utf-8")
+
+    lock = acquire_lock(audit_lock_key(root, path))
+    if lock is None:
+        raise OverrideAppendError("another writer holds the overrides.log audit path lock")
+    fd = None
+    try:
+        if path.read_bytes() != before:
+            raise OverrideAppendError("overrides.log changed during validation; retry")
+        flags = os.O_APPEND | os.O_WRONLY
+        if hasattr(os, "O_BINARY"):
+            flags |= os.O_BINARY
+        fd = os.open(path, flags)
+        offset = 0
+        while offset < len(line):
+            written = os.write(fd, line[offset:])
+            if written <= 0:
+                raise OverrideAppendError("override audit append made no progress")
+            offset += written
+        os.fsync(fd)
+    except OSError as error:
+        raise OverrideAppendError(f"override audit append failed: {error}") from error
+    finally:
+        try:
+            if fd is not None:
+                os.close(fd)
+        finally:
+            release_lock(lock)
+    return path
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Append one mandatory override audit row safely.")
+    kind = parser.add_mutually_exclusive_group(required=True)
+    kind.add_argument("--gate", help="gate identifier for an ordinary override")
+    kind.add_argument("--security-finding", help="specific acknowledged security finding")
+    parser.add_argument("--reason", required=True, help="specific justification")
+    args = parser.parse_args(argv)
+    try:
+        path = append_override(
+            gate=args.gate,
+            security_finding=args.security_finding,
+            reason=args.reason,
+        )
+    except (OSError, OverrideAppendError) as error:
+        print(f"override audit append refused: {error}", file=sys.stderr)
+        return 1
+    print(f"appended mandatory override audit row: {path}")
+    return 0

package/plugins/ca-pi/hooks/_taskboardlib.py

@@ -704,6 +704,23 @@ ARCHIVE_CUTOFF_DAYS = 14
 
 DONE_TASKS_HEADING = "# Done tasks"
 
+# The canonical documented archive template, shared by init and first use.
+DONE_TASKS = """\
+# Done tasks
+
+Completed work swept off the board by `taskwrite archive`, newest last.
+APPEND-ONLY: entries are added here and never edited or removed, so a
+finished task has exactly one permanent record.
+
+Each archived task preserves its original lifecycle line and indented task block verbatim
+from `open-tasks.md`. The lifecycle line keeps its `(done YYYY-MM-DD)` stamp
+intact — the stamp is what makes an entry ageable, and what `archive` refuses
+to invent.
+
+Written only by `taskwrite archive`. `/ca:standup` proposes the sweep with
+per-item confirmation; nothing sweeps automatically.
+"""
+
 
 def archive_candidates(text, *, today, cutoff_days=ARCHIVE_CUTOFF_DAYS):
     """`(aged, undated)` — done tasks eligible for the archival sweep.
@@ -862,7 +879,7 @@ def archive_transform(open_text, done_text, task):
     if already_archived(done_text, task):
         new_done = done_text
     else:
-        body = done_text if done_text.strip() else DONE_TASKS_HEADING + "\n"
+        body = done_text if done_text.strip() else DONE_TASKS
         if not body.endswith("\n"):
             body += "\n"
         new_done = body + "\n".join(block) + "\n"

package/plugins/ca-pi/hooks/_taskexcludelib.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+# codeArbiter — locally exclude the retained task-board OS-lock sidecar.
+#
+# The board lock is intentionally never removed: unlinking a locked inode lets
+# another process acquire a different lock. Only Git's common info/exclude is
+# changed, through its own exclusive create/replace lockfile protocol. Existing
+# bytes and modes survive; no tracked file or Git index is written.
+# Static Git-metadata link/reparse aliases and observed concurrent edits fail closed. This
+# cooperates with writers honoring exclude.lock; it is not a sandbox against a
+# hostile same-user process swapping paths between filesystem operations.
+#
+# Public API:
+#   ensure_task_lock_excluded(root, required=False) -> str | None
+#       "added" / "already present", or None for optional non-Git scaffolding.
+#       Raises TaskExclusionError with a surfaced diagnostic on unsafe/failing IO.
+
+import os
+from pathlib import Path
+import stat
+import subprocess
+
+from _gitexec import git_executable, root_bound_git_env
+
+
+LOCK_PATH = ".codearbiter/open-tasks.md.lock"
+EXCLUDE_RULE = b"/" + LOCK_PATH.encode("ascii")
+MAX_EXCLUDE_BYTES = 2 * 1024 * 1024
+_REPARSE = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+
+
+class TaskExclusionError(RuntimeError):
+    pass
+
+
+def _version(info):
+    # Windows Python can expose creation time via lstat().st_ctime but change
+    # time via fstat().st_ctime. Compare the common birth-time field there;
+    # identity, size, mtime, mode/link count and byte rereads still bind edits.
+    change = getattr(info, "st_birthtime_ns", 0) if os.name == "nt" else info.st_ctime_ns
+    return (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns,
+            change, info.st_mode, info.st_nlink)
+
+
+def _regular(info):
+    return (stat.S_ISREG(info.st_mode) and info.st_nlink == 1
+            and not getattr(info, "st_file_attributes", 0) & _REPARSE)
+
+
+def _directories(path):
+    for directory in (*reversed(path.parents), path):
+        info = directory.lstat()
+        if not stat.S_ISDIR(info.st_mode) or getattr(info, "st_file_attributes", 0) & _REPARSE:
+            raise TaskExclusionError("unsafe directory in task lock exclusion path")
+
+
+def _git(root, *args, input_bytes=None):
+    return subprocess.run([git_executable(), "-C", str(root), *args],
+                          env=root_bound_git_env(), capture_output=True, timeout=5,
+                          input=input_bytes)
+
+
+def _git_path(root, *args):
+    result = _git(root, "rev-parse", *args)
+    value = os.fsdecode(result.stdout).rstrip("\r\n")
+    if result.returncode or not value or not os.path.isabs(value) or "\n" in value:
+        raise TaskExclusionError("cannot bind task lock exclusion to selected Git")
+    return Path(value)
+
+
+def _same_path(left, right):
+    return os.path.normcase(os.path.abspath(left)) == os.path.normcase(os.path.abspath(right))
+
+
+def _binding(root, required):
+    # A failed Git probe in an actual checkout is never mistaken for non-Git.
+    markers = [item / ".git" for item in (root, *root.parents)]
+    has_marker = any(os.path.lexists(path) for path in markers)
+    try:
+        top = _git_path(root, "--show-toplevel")
+    except (OSError, RuntimeError, subprocess.SubprocessError):
+        if not required and not has_marker:
+            return None
+        raise TaskExclusionError("cannot resolve repository root for task lock exclusion") from None
+    # Git reports physical roots: /var aliases and Windows 8.3 names can differ
+    # from the caller. Resolve only this identity, never metadata paths whose
+    # unresolved link/reparse attributes the checks below must inspect.
+    root = Path(os.path.realpath(root))
+    if not _same_path(os.path.realpath(top), root):
+        raise TaskExclusionError("task lock exclusion requires the exact repository root")
+    _directories(root)
+    marker = root / ".git"
+    info = marker.lstat()
+    if (not (stat.S_ISDIR(info.st_mode) or _regular(info))
+            or getattr(info, "st_file_attributes", 0) & _REPARSE):
+        raise TaskExclusionError("unsafe Git marker for task lock exclusion")
+    common = _git_path(root, "--path-format=absolute", "--git-common-dir")
+    exclude = _git_path(root, "--path-format=absolute", "--git-path", "info/exclude")
+    if not _same_path(exclude, common / "info/exclude"):
+        raise TaskExclusionError("task lock exclusion common-directory mismatch")
+    _directories(common)
+    return exclude
+
+
+def _read_exclude(path):
+    try:
+        before = path.lstat()
+    except FileNotFoundError:
+        return b"", None
+    if not _regular(before):
+        raise TaskExclusionError("task lock exclusion is not a regular single-link file")
+    fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    with os.fdopen(fd, "rb") as handle:
+        opened = os.fstat(handle.fileno())
+        if not _regular(opened) or _version(opened) != _version(before):
+            raise TaskExclusionError("task lock exclusion changed while opening")
+        data = handle.read(MAX_EXCLUDE_BYTES + 1)
+        if len(data) > MAX_EXCLUDE_BYTES:
+            raise TaskExclusionError("task lock exclusion exceeds size limit")
+        if _version(os.fstat(handle.fileno())) != _version(before):
+            raise TaskExclusionError("task lock exclusion changed while reading")
+    if _version(path.lstat()) != _version(before):
+        raise TaskExclusionError("task lock exclusion path changed while reading")
+    return data, before
+
+
+def _check_conflicts(root):
+    tracked = _git(root, "ls-files", "--error-unmatch", "--", LOCK_PATH)
+    if tracked.returncode == 0:
+        raise TaskExclusionError("task lock sidecar is tracked; local exclusion cannot untrack it")
+    if tracked.returncode != 1:
+        raise TaskExclusionError("cannot check tracked task lock sidecar")
+    # A file can serve both global and per-directory roles. For this conflict
+    # probe only, disable the lower-priority global source without changing
+    # repository configuration. Effectiveness checks below use actual config.
+    ignored = _git(root, "-c", "core.excludesFile=", "check-ignore", "--no-index", "-z", "-v", "--stdin",
+                   input_bytes=LOCK_PATH.encode("ascii") + b"\0")
+    if ignored.returncode not in (0, 1):
+        raise TaskExclusionError("cannot check task lock exclusion precedence")
+    fields = ignored.stdout.split(b"\0")
+    # Git reports the target's per-directory sources relative to the -C root.
+    if len(fields) == 5 and fields[0].replace(b"\\", b"/") in (
+            b".gitignore", b".codearbiter/.gitignore") \
+            and fields[2].startswith(b"!"):
+        raise TaskExclusionError("a .gitignore negation overrides local task lock exclusion")
+
+
+def _ensure(root, required):
+    # Retain the caller spelling so publication-time binding detects retargeting.
+    root = Path(os.path.abspath(root))
+    exclude = _binding(root, required)
+    if exclude is None:
+        return None
+    # mkdir is exclusive and never follows a preexisting info alias.
+    try:
+        exclude.parent.mkdir()
+    except FileExistsError:
+        pass
+    _directories(exclude.parent)
+    lock = exclude.with_name("exclude.lock")
+    fd = None
+    owned = None
+    try:
+        try:
+            fd = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL
+                         | getattr(os, "O_NOFOLLOW", 0), 0o666)
+        except FileExistsError:
+            raise TaskExclusionError("exclude.lock already exists; another writer may own it") from None
+        info = os.fstat(fd)
+        owned = info.st_dev, info.st_ino
+        before, snapshot = _read_exclude(exclude)
+        _check_conflicts(root)
+        if EXCLUDE_RULE in before.splitlines():
+            ignored = _git(root, "check-ignore", "-q", "--", LOCK_PATH)
+            if ignored.returncode == 0:
+                return "already present"
+            if ignored.returncode != 1:
+                raise TaskExclusionError("cannot verify task lock exclusion")
+        newline = b"\r\n" if b"\r\n" in before else b"\n"
+        data = before + (newline if before and not before.endswith(b"\n") else b"")
+        data += EXCLUDE_RULE + newline
+        if len(data) > MAX_EXCLUDE_BYTES:
+            raise TaskExclusionError("task lock exclusion output exceeds size limit")
+        with os.fdopen(fd, "wb") as handle:
+            fd = None
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if snapshot is not None:
+            os.chmod(lock, stat.S_IMODE(snapshot.st_mode))
+        latest, current = _read_exclude(exclude)
+        if latest != before or ((snapshot is None) != (current is None)) \
+                or snapshot is not None and _version(snapshot) != _version(current):
+            raise TaskExclusionError("task lock exclusion changed before publication")
+        if _binding(root, True) != exclude:
+            raise TaskExclusionError("task lock exclusion binding changed before publication")
+        _directories(exclude.parent)
+        info = lock.lstat()
+        if not _regular(info) or (info.st_dev, info.st_ino) != owned:
+            raise TaskExclusionError("exclude.lock ownership changed before publication")
+        os.replace(lock, exclude)
+        owned = None
+        if _git(root, "check-ignore", "-q", "--", LOCK_PATH).returncode != 0:
+            raise TaskExclusionError("local rule added but task lock exclusion is not effective")
+        return "added"
+    finally:
+        if fd is not None:
+            os.close(fd)
+        if owned is not None:
+            try:
+                info = lock.lstat()
+                if (info.st_dev, info.st_ino) == owned:
+                    lock.unlink()  # Only OUR Git transaction file, NEVER the board OS lock.
+            except FileNotFoundError:
+                pass
+
+
+def ensure_task_lock_excluded(root, required=False):
+    try:
+        return _ensure(root, required)
+    except TaskExclusionError:
+        raise
+    except (OSError, RuntimeError, subprocess.SubprocessError) as exc:
+        raise TaskExclusionError(f"task lock exclusion failed ({type(exc).__name__})") from None

package/plugins/ca-pi/hooks/append-override.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""CLI entry point for the locked mandatory override audit append."""
+
+from _overrideappendlib import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/ca-pi/hooks/hostapi.py

@@ -313,7 +313,7 @@ class Host:
 
     name = "claude"
     adapter_name = "ca"
-    adapter_version = "2.17.7"
+    adapter_version = "2.17.10"
 
     # Update-notifier descriptor. Each independently versioned host overrides
     # these three values in its per-plugin _host.py. Keeping the target,

package/plugins/ca-pi/hooks/init-codearbiter.py

@@ -12,6 +12,7 @@
 # Usage:
 #   python init-codearbiter.py [--root PATH] [--stage N]
 #   python init-codearbiter.py --check        # report state, create nothing
+#   python init-codearbiter.py --repair-lock-exclusion [--root PATH]
 
 import argparse
 import subprocess
@@ -19,7 +20,8 @@ import os
 import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from _gitexec import git_executable  # noqa: E402
+from _gitexec import git_executable, root_bound_git_env  # noqa: E402
+from _taskboardlib import DONE_TASKS  # noqa: E402 — shared archive template (#625)
 import hostapi  # noqa: E402 — host seam (ADR-0011)
 import _hooklib  # noqa: E402 — set_host DI seam (#257)
 import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
@@ -92,21 +94,6 @@ OVERRIDES = """\
 # last-checkpoint marker as "overrides since last checkpoint."
 """
 
-DONE_TASKS = """\
-# Done tasks
-
-Completed work swept off the board by `taskwrite archive`, newest last.
-APPEND-ONLY: entries are added here and never edited or removed, so a
-finished task has exactly one permanent record.
-
-Each line is the task's original lifecycle line, moved verbatim from
-`open-tasks.md` with its `(done YYYY-MM-DD)` stamp intact — the stamp is
-what makes an entry ageable, and what `archive` refuses to invent.
-
-Written only by `taskwrite archive`. `/ca:standup` proposes the sweep with
-per-item confirmation; nothing sweeps automatically.
-"""
-
 FILES = {
     "open-tasks.md": OPEN_TASKS,
     # B-23: scaffolded at init rather than created on first archive. An
@@ -126,7 +113,7 @@ def project_root(opt):
     # prefer git toplevel; fall back to cwd
     try:
         out = subprocess.run([git_executable(), "rev-parse", "--show-toplevel"],
-                             capture_output=True, text=True, timeout=2)
+                             env=root_bound_git_env(), capture_output=True, text=True, timeout=2)
         top = out.stdout.strip()
         if out.returncode == 0 and top:
             return os.path.abspath(top)
@@ -138,9 +125,16 @@ def project_root(opt):
 def main(argv=None):
     ap = argparse.ArgumentParser(add_help=True)
     ap.add_argument("--root")
-    ap.add_argument("--stage", type=int, default=1)
+    ap.add_argument("--stage", type=int)
     ap.add_argument("--check", action="store_true")
+    ap.add_argument("--repair-lock-exclusion", action="store_true", help=(
+        "repair only Git-local info/exclude for an existing scaffold; retain the "
+        "task-board OS lock, never rewrite project state (cannot combine with --check/--stage)"))
     args = ap.parse_args(argv)
+    if args.repair_lock_exclusion and (args.check or args.stage is not None):
+        ap.error("--repair-lock-exclusion cannot combine with --check or --stage")
+    if args.stage is None:
+        args.stage = 1
 
     root = project_root(args.root)
     cad = os.path.join(root, ".codearbiter")
@@ -168,11 +162,29 @@ def main(argv=None):
             print(f"NOT SCAFFOLDED: {cad} would be created. Run without --check to scaffold.")
         return
 
+    from _taskexcludelib import ensure_task_lock_excluded, TaskExclusionError
+    if args.repair_lock_exclusion:
+        if not os.path.isfile(ctx) or os.path.islink(ctx):
+            raise SystemExit("REFUSING: task lock exclusion repair requires an existing scaffold.")
+        try:
+            result = ensure_task_lock_excluded(root, required=True)
+        except TaskExclusionError as exc:
+            raise SystemExit(f"REFUSING: {exc}") from None
+        print(f"task lock exclusion: {result}")
+        return
+
     if os.path.exists(ctx):
         raise SystemExit(
             f"REFUSING: {ctx} already exists. .codearbiter/ is already scaffolded here. "
             f"To populate it, run {_cc} or {_dc}; to repair, edit by hand.")
 
+    try:
+        result = ensure_task_lock_excluded(root)
+    except TaskExclusionError as exc:
+        raise SystemExit(f"REFUSING: {exc}") from None
+    if result:
+        print(f"task lock exclusion: {result}")
+
     os.makedirs(cad, exist_ok=True)
     created = []
     if not os.path.exists(ctx):
@@ -183,7 +195,10 @@ def main(argv=None):
     for fname, content in FILES.items():
         fp = os.path.join(cad, fname)
         if not os.path.exists(fp):
-            with open(fp, "w", encoding="utf-8") as f:
+            # Match taskwrite's LF output for this shared append-only template
+            # on Windows too; other scaffold files retain their existing EOLs.
+            newline = "\n" if fname == "done-tasks.md" else None
+            with open(fp, "w", encoding="utf-8", newline=newline) as f:
                 f.write(content)
             created.append(fname)
 

package/plugins/ca-pi/hooks/resolve-append-only-conflict.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+# codeArbiter - sanctioned helper entry point for H-05 append-only conflicts.
+
+from _appendonlyconflictlib import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/ca-pi/skills/ca-override/SKILL.md

@@ -15,14 +15,40 @@ logged, always visible, never silent. Single identity, single confirm.
    vague reason ("just skip it") and ask for a specific one.
 2. Detect the operator identity from `git config user.email` only. If it is unset, ask the user once
    to state their identity for the log. (No platform ladder, no second confirmation.)
-3. Append one line to `<project-root>/.codearbiter/overrides.log`:
+3. For an ordinary override, use the private locked audit helper from the repository root:
+
+   ```sh
+   python3 "<plugin-root>/hooks/append-override.py" --gate "<gate bypassed>" --reason "<specific reason>"
+   ```
+
+   It appends one line to `<project-root>/.codearbiter/overrides.log`:
 
    ```
    [ISO-8601 timestamp] | BY: <email> | GATE: <gate bypassed> | REASON: <reason>
    ```
 
-   The log is append-only — never edited or deleted, committed as a permanent audit artifact.
-4. Proceed with the overridden action. Note in the response that the override is logged.
+   The log is append-only — never edited or deleted, committed as a permanent audit artifact. The
+   helper fails closed if another official writer or conflict resolver owns the audit-path lock; the
+   overridden action must not proceed unless the row lands. A guard-permitted raw append remains a
+   cooperative operator escape hatch, but it must not run concurrently with conflict resolution.
+4. A genuine three-stage Git conflict on an H-05 append-only path uses the dedicated helper instead
+   of the ordinary step 3 append. Run it once from the conflicted repository, with the specific
+   repo-relative path and the same reason:
+
+   ```sh
+   python3 "<plugin-root>/hooks/resolve-append-only-conflict.py" ".codearbiter/overrides.log" --reason "<specific reason>"
+   ```
+
+   The helper derives the same `git config user.email` identity, validates the merge-base and both
+   append suffixes, writes the attributed H-05 record, and explicitly stages only the validated
+   deterministic union. It refuses a missing or malformed three-stage conflict, any edit to prior
+   bytes, unsupported paths, invalid encoding, dirty audit sink, or replay after resolution. This is
+   scoped to the immediate action only; it creates no marker, standing exception, or general H-05
+   bypass. It takes canonical per-audit-path locks and supports only `overrides.log` and the
+   repository-owned `gate-events.log` sink; official writers share those locks. Conflict resolution
+   is an exclusive cooperative operation: do not start a raw append before or during it. Never
+   hand-resolve the protected log with Write, patch, checkout, or restore.
+5. Proceed with the overridden action. Note in the response that the override is logged.
 
 ## Security ceiling — heavier path for security-critical stops
 
@@ -40,8 +66,14 @@ Heavier path (all required, in order):
 2. **Explicit per-finding acknowledgement** — the user must acknowledge *that specific finding* in
    their own words (a bare "yes"/"go ahead"/"I trust you" is declined — this mirrors `decision-variance`).
    Detect identity from `git config user.email`; if unset, ask once.
-3. **Heavier log entry** — append a line tagged `SECURITY-OVERRIDE` that records the specific finding,
-   not just the gate name:
+3. **Heavier log entry** — use the same locked helper so the mandatory row cannot race conflict
+   resolution:
+
+   ```sh
+   python3 "<plugin-root>/hooks/append-override.py" --security-finding "<specific finding>" --reason "<reason>"
+   ```
+
+   It appends a line tagged `SECURITY-OVERRIDE` that records the specific finding, not just the gate name:
 
    ```
    [ISO-8601] | BY: <email> | SECURITY-OVERRIDE | FINDING: <specific finding> | REASON: <reason>
@@ -62,7 +94,9 @@ Under `/ca-sprint`, a security-critical override is a hard-gate STOP: it surface
 MUST write the log line before proceeding — it is not optional. MUST capture an operator identity —
 "codeArbiter" or "automated" are not valid. MUST include a justification. The override is scoped to
 the immediate action only; it creates no standing exception. MUST NOT edit or delete an existing
-`overrides.log` entry. MUST route a security-critical / crypto-secret / irreversible stop through the
+`overrides.log` entry. For an H-05 three-stage conflict, the dedicated helper's validated union and
+audit write are the single immediate action; do not pre-edit the conflicted file. MUST route a
+security-critical / crypto-secret / irreversible stop through the
 **Security ceiling** path — never the single-confirm flow — and MUST NOT auto-decide such an override
 under `/ca-sprint`.