@arbiterforge/ca-pi 0.10.8 → 0.10.10

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.9" src="https://img.shields.io/badge/version-2.17.9-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.9`;
 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.10",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `ca-pi` are documented in this file.
 
 ## [Unreleased]
 
+## [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/_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.10"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

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/hostapi.py

@@ -313,7 +313,7 @@ class Host:
 
     name = "claude"
     adapter_name = "ca"
-    adapter_version = "2.17.7"
+    adapter_version = "2.17.9"
 
     # 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)