@delorenj/pjangler 1.4.2 → 1.4.4

package/templates/hermes-agent/template/.scripts/config.example.toml

@@ -35,9 +35,15 @@ oauth_file = "~/.hermes/auth.json"
 codex_home = "~/.codex"
 # Canonical external skills dir mirrored into each agent profile.
 canonical_skills_dir = "/home/delorenj/.agents/skills"
-# Voxxy plugin + service defaults for Hermes PM agents.
-voxxy_plugin_dir = "~/code/voxxy/plugins/tts/voxxy"
+# Optional Vox plugin + service defaults for Hermes PM agents.
+vox_plugin_name = "vox"
+vox_plugin_dir = "~/code/voxxy/plugins/tts/vox"
+vox_voice = "carlin"
 vox_url = "https://vox.delo.sh"
+# Channel credentials are written directly to Password items in this vault;
+# only op:// references are recorded in named-profile config.delta.yaml.
+onepassword_vault = "DeLoSecrets"
+onepassword_item_prefix = "hermes-agent"
 # Canonical PM config.yaml the provisioner seeds each runtime's config.yaml from.
 # This is the fleet-wide Hermes inference/skill config (model, toolsets, etc.)
 # every agent runtime starts from. ~ is expanded.

package/templates/hermes-agent/template/.scripts/credential-launch.sh

@@ -45,6 +45,11 @@ if ! REPO_ROOT="$(git -C "$ROLE_DIR" rev-parse --show-toplevel 2>/dev/null)"; th
 fi
 export TERMINAL_CWD="$REPO_ROOT"
 
+# Do not forward a stale/raw channel value inherited from the service manager,
+# login shell, or a legacy runtime EnvironmentFile. Hermes hydrates the named
+# profile's validated 1Password references after this launcher execs it.
+unset TELEGRAM_BOT_TOKEN SLACK_BOT_TOKEN SLACK_APP_TOKEN
+
 load_credential() {
   local credential_id="$1" env_name="$2" credential_file value
   [[ "$env_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] \
@@ -57,7 +62,6 @@ load_credential() {
   unset value
 }
 
-load_credential telegram_bot_token TELEGRAM_BOT_TOKEN
 MODEL_KEY_ENV="$(yaml_get model.key_env)"
 if [[ -n "$MODEL_KEY_ENV" ]]; then
   load_credential model_api_key "$MODEL_KEY_ENV"

package/templates/hermes-agent/template/.scripts/heartbeat.sh

@@ -145,9 +145,8 @@ else
 fi
 
 # Reconcile gate: the autonomous board-reconciliation pass runs only when
-# role.yaml's reconcile.enabled is true. Default off → the heartbeat just
-# checkpoints (behaves like the legacy hourly checkpoint timer). Flip
-# reconcile.enabled to opt a repo into autonomous board reconciliation.
+# role.yaml's reconcile.enabled is true. Deployed PMs default on; setting it
+# false explicitly opts into checkpoint-only operation.
 if [[ "$(reconcile_enabled)" != "true" ]]; then
   printf '[heartbeat] reconcile disabled (reconcile.enabled != true) — checkpoint-only tick\n'
   maybe_checkpoint

package/templates/hermes-agent/template/.scripts/lib/profile-config-lock.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Shared serialization for one Hermes profile's generated configuration.
+
+All code that can read and then rewrite ``config.delta.yaml`` or ``config.yaml``
+must hold this lock from topology validation through commit or rollback.  A
+channel transaction already holds the fleet registry lock before it enters this
+lock; config-only reconcilers never acquire the registry lock.  The only valid
+ordering is therefore::
+
+    fleet registry lock -> profile config lock
+
+Never acquire the fleet registry lock while holding a profile config lock.
+``flock`` ownership is kernel-scoped, so process exit releases the lock even
+though the deliberately persistent lock file remains on disk.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import pathlib
+import stat
+import time
+from types import TracebackType
+from typing import Self
+
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+LOCK_TIMEOUT_ENV = "HERMES_PROFILE_CONFIG_LOCK_TIMEOUT_SECONDS"
+TEST_BARRIER_ENV = "PJANGLER_TEST_PROFILE_CONFIG_BARRIER"
+TEST_BARRIER_TIMEOUT_ENV = "PJANGLER_TEST_PROFILE_CONFIG_BARRIER_TIMEOUT_SECONDS"
+TEST_BARRIER_LABEL_ENV = "PJANGLER_TEST_PROFILE_CONFIG_BARRIER_LABEL"
+TEST_LOCK_ATTEMPT_ENV = "PJANGLER_TEST_PROFILE_CONFIG_LOCK_ATTEMPT"
+
+
+class ProfileConfigLockError(RuntimeError):
+    """The profile lock could not be acquired safely."""
+
+
+def lock_path(profile: pathlib.Path) -> pathlib.Path:
+    """Return a lock path that does not require following the profile root."""
+
+    return profile.parent / f".{profile.name}.config.lock"
+
+
+def _timeout_seconds() -> float:
+    raw = os.environ.get(LOCK_TIMEOUT_ENV, str(DEFAULT_TIMEOUT_SECONDS))
+    try:
+        timeout = float(raw)
+    except ValueError as exc:
+        raise ProfileConfigLockError(
+            f"{LOCK_TIMEOUT_ENV} must be a non-negative number"
+        ) from exc
+    if timeout < 0 or timeout != timeout:
+        raise ProfileConfigLockError(
+            f"{LOCK_TIMEOUT_ENV} must be a non-negative number"
+        )
+    return timeout
+
+
+class ProfileConfigLock:
+    """Exclusive, bounded, symlink-safe lock for one profile config pair."""
+
+    def __init__(self, profile: pathlib.Path | str, timeout: float | None = None):
+        self.profile = pathlib.Path(profile)
+        self.path = lock_path(self.profile)
+        self.timeout = _timeout_seconds() if timeout is None else timeout
+        self.fd: int | None = None
+
+    def acquire(self) -> Self:
+        parent = self.profile.parent
+        if parent.is_symlink() or not parent.is_dir():
+            raise ProfileConfigLockError(
+                f"profile parent must be a real directory before locking: {parent}"
+            )
+        if self.path.is_symlink():
+            raise ProfileConfigLockError(
+                f"refusing profile config lock symlink: {self.path}"
+            )
+        flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_CLOEXEC", 0)
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+        try:
+            fd = os.open(self.path, flags, 0o600)
+        except OSError as exc:
+            raise ProfileConfigLockError(
+                f"cannot open profile config lock {self.path}: {exc.strerror or type(exc).__name__}"
+            ) from exc
+        try:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                raise ProfileConfigLockError(
+                    f"profile config lock is not a regular file: {self.path}"
+                )
+            os.fchmod(fd, 0o600)
+            _notify_test_lock_attempt(self.path)
+            deadline = time.monotonic() + self.timeout
+            while True:
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError as exc:
+                    if time.monotonic() >= deadline:
+                        raise ProfileConfigLockError(
+                            f"timed out waiting for profile config lock: {self.path}"
+                        ) from exc
+                    time.sleep(min(0.05, max(0.0, deadline - time.monotonic())))
+        except BaseException:
+            os.close(fd)
+            raise
+        self.fd = fd
+        return self
+
+    def release(self) -> None:
+        if self.fd is None:
+            return
+        fd, self.fd = self.fd, None
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
+
+    def __enter__(self) -> Self:
+        return self.acquire()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.release()
+
+
+def _test_path_from_env(name: str) -> pathlib.Path | None:
+    configured = os.environ.get(name)
+    if not configured:
+        return None
+    if "PYTEST_CURRENT_TEST" not in os.environ:
+        raise ProfileConfigLockError(
+            f"{name} is test-only and requires a pytest process"
+        )
+    path = pathlib.Path(configured)
+    if path.is_symlink() or path.parent.is_symlink() or not path.parent.is_dir():
+        raise ProfileConfigLockError(f"unsafe test profile-config path: {path}")
+    return path
+
+
+def _notify_test_lock_attempt(lock: pathlib.Path) -> None:
+    target = _test_path_from_env(TEST_LOCK_ATTEMPT_ENV)
+    if target is not None:
+        target.write_text(str(lock) + "\n", encoding="utf-8")
+
+
+def test_snapshot_barrier(label: str) -> None:
+    """Pause a test process after its locked snapshot has been captured.
+
+    This hook is inert outside pytest.  It exists so the regression suite can
+    deterministically exercise the stale-snapshot interleaving that motivated
+    this lock without widening the production interface.
+    """
+
+    selected_label = os.environ.get(TEST_BARRIER_LABEL_ENV)
+    if selected_label and selected_label != label:
+        return
+    barrier = _test_path_from_env(TEST_BARRIER_ENV)
+    if barrier is None:
+        return
+    ready = pathlib.Path(f"{barrier}.ready")
+    resume = pathlib.Path(f"{barrier}.resume")
+    ready.write_text(label + "\n", encoding="utf-8")
+    try:
+        timeout = float(os.environ.get(TEST_BARRIER_TIMEOUT_ENV, "15"))
+    except ValueError as exc:
+        raise ProfileConfigLockError(
+            f"{TEST_BARRIER_TIMEOUT_ENV} must be a positive number"
+        ) from exc
+    deadline = time.monotonic() + timeout
+    while not resume.is_file():
+        if time.monotonic() >= deadline:
+            raise ProfileConfigLockError(
+                f"timed out waiting at test profile-config barrier: {barrier}"
+            )
+        time.sleep(0.02)

package/templates/hermes-agent/template/.scripts/lib/profile-config-seed.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Seed a named profile's override delta under the shared profile lock."""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import importlib.util
+import os
+import pathlib
+import stat
+import tempfile
+
+SEED_CONTENT = (
+    "# Override-only delta for this Hermes profile.\n"
+    "# Merged over ~/.hermes/config.yaml to produce config.yaml (which is GENERATED).\n"
+    "# Empty == identical to the fleet base. Add ONLY what must differ.\n"
+    "{}\n"
+).encode("utf-8")
+
+
+def load_profile_lock_module():
+    source = pathlib.Path(__file__).parent / "profile-config-lock.py"
+    if source.is_symlink() or not source.is_file():
+        raise RuntimeError(
+            f"trusted profile config lock helper is unavailable: {source}"
+        )
+    spec = importlib.util.spec_from_file_location(
+        "pjangler_profile_config_lock", source
+    )
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load profile config lock helper: {source}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+PROFILE_LOCK = load_profile_lock_module()
+
+
+def fsync_parent(path: pathlib.Path) -> None:
+    unsupported = {errno.EINVAL, getattr(errno, "ENOTSUP", errno.EINVAL), errno.ENOSYS}
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        directory_fd = os.open(path.parent, flags)
+    except OSError as exc:
+        if exc.errno in unsupported:
+            return
+        raise
+    try:
+        try:
+            os.fsync(directory_fd)
+        except OSError as exc:
+            if exc.errno not in unsupported:
+                raise
+    finally:
+        os.close(directory_fd)
+
+
+def seed(profile: pathlib.Path) -> str:
+    with PROFILE_LOCK.ProfileConfigLock(profile):
+        PROFILE_LOCK.test_snapshot_barrier("seed")
+        if profile.is_symlink() or not profile.is_dir():
+            raise RuntimeError(f"profile root must be a real directory: {profile}")
+        target = profile / "config.delta.yaml"
+        if target.is_symlink():
+            raise RuntimeError(f"refusing config delta symlink: {target}")
+        if target.exists():
+            if not target.is_file():
+                raise RuntimeError(f"config delta is not a regular file: {target}")
+            return "exists"
+
+        descriptor, temporary_name = tempfile.mkstemp(
+            prefix=".config.delta.yaml.seed-", dir=profile
+        )
+        temporary = pathlib.Path(temporary_name)
+        try:
+            os.fchmod(descriptor, 0o600)
+            with os.fdopen(descriptor, "wb") as handle:
+                handle.write(SEED_CONTENT)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, target)
+            os.chmod(target, stat.S_IRUSR | stat.S_IWUSR)
+            fsync_parent(target)
+        except BaseException:
+            try:
+                temporary.unlink()
+            except FileNotFoundError:
+                pass
+            raise
+        return "seeded"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--profile", required=True)
+    args = parser.parse_args()
+    try:
+        print(seed(pathlib.Path(args.profile)))
+    except PROFILE_LOCK.ProfileConfigLockError as exc:
+        raise SystemExit(f"profile config seed failed: {exc}") from exc
+    except (OSError, RuntimeError) as exc:
+        raise SystemExit(f"profile config seed failed: {exc}") from exc
+
+
+if __name__ == "__main__":
+    main()

package/templates/hermes-agent/template/.scripts/lib/ticket-provider.sh

@@ -10,15 +10,25 @@
 #   resolve                       -> JSON {provider, board_id, board_url}
 #   active_milestone              -> JSON {id, name, state}
 #   list_issues                   -> JSON [ {id,key,title,state,state_type,
-#                                            updated_at,assignee,url}, ... ]
-#   get_issue <id>                -> JSON {id,key,title,description,acceptance,
+#                                            updated_at,assignee,url,...}, ... ]
+#   get_issue <issue-ref>         -> JSON {id,key,title,description,acceptance,
 #                                          state,state_type,comments:[...],
 #                                          attachments:[...]}
-#   comment <id> <body>           -> prints comment id
-#   transition <id> <normalized>  -> moves issue; normalized in
+#   comment <issue-ref> <body>    -> prints comment id
+#   transition <issue-ref> <normalized>
+#                                 -> resolves id/human key, then moves issue; normalized in
 #                                     backlog|unstarted|started|in_review|completed|
 #                                     cancelled
 #   create_board <name> <id> <d>  -> JSON {board_id, board_url}
+#   describe_board <ws> <board_id>
+#                                 -> JSON {board_id, identifier, workspace,
+#                                          name}
+#                                    Read-only lookup against an EXPLICIT
+#                                    workspace, so no ambient binding can send
+#                                    the query elsewhere. `identifier` is
+#                                    whatever the provider itself reports, and
+#                                    is empty when the provider mints none
+#                                    (Trello). Never a locally-computed guess.
 #   create_issue [--if-absent] <title> [desc]
 #                                 -> JSON {issue_id, key, issue_url, created}
 #                                    Files a new ticket on the bound board.
@@ -29,6 +39,63 @@
 # Each provider reads its credentials from the environment (see providers/*.sh
 # headers) and the board binding from repo-root .project.json.
 
+# Read the human key prefix from the project binding. Plane list_issues exposes
+# sequence_id as a number while people use PREFIX-number; the dispatcher owns
+# that provider-neutral seam so callers never have to know the native id shape.
+tp_project_identifier() {
+  local role_dir
+  role_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+  python3 - "$role_dir" <<'PY' 2>/dev/null
+import json
+import pathlib
+import sys
+
+start = pathlib.Path(sys.argv[1]).resolve()
+for parent in [start, *start.parents]:
+    manifest = parent / ".project.json"
+    if manifest.is_file():
+        try:
+            provider = json.loads(manifest.read_text()).get("ticket_provider") or {}
+            print(str(provider.get("identifier") or ""))
+        except Exception:
+            print("")
+        break
+else:
+    print("")
+PY
+}
+
+# Resolve an id, provider key, or project-prefixed numeric key against the
+# normalized list contract. Mutating operations fail before reaching a provider
+# if the reference is absent or ambiguous.
+tp_resolve_issue_reference() {
+  local name="$1" impl="$2" reference="$3" identifier issues
+  identifier="$(tp_project_identifier)"
+  issues="$(TICKET_PROVIDER="$name" sh "$impl" list_issues)" || return 1
+  TP_REFERENCE="$reference" TP_IDENTIFIER="$identifier" python3 -c 'import json,os,sys
+reference=os.environ["TP_REFERENCE"].strip(); identifier=os.environ.get("TP_IDENTIFIER", "").strip()
+try:
+    data=json.load(sys.stdin)
+except Exception as exc:
+    raise SystemExit(f"tp: could not resolve issue reference {reference!r}: list_issues returned invalid JSON ({exc})")
+rows=data if isinstance(data,list) else data.get("results", []) if isinstance(data,dict) else []
+want=reference.casefold(); matches=[]
+for issue in rows:
+    native=str(issue.get("id") or "").strip(); key=str(issue.get("key") or "").strip()
+    aliases={native.casefold(), key.casefold()}
+    if identifier and key.isdigit():
+        aliases.add(f"{identifier}-{key}".casefold())
+    if native and want in aliases:
+        matches.append(native)
+matches=list(dict.fromkeys(matches))
+if len(matches) != 1:
+    detail="not found" if not matches else "ambiguous"
+    raise SystemExit(f"tp: could not resolve issue reference {reference!r}: {detail}")
+print(matches[0])' <<EOF
+$issues
+EOF
+}
+
 # Resolve the provider name: explicit env wins, then repo-root .project.json
 # (the SOT), then role.yaml (self-parsed so this works even when _lib.sh /
 # yaml_get is not loaded), then default.
@@ -87,6 +154,19 @@ tp() {
   local op="${1:-}"; shift || true
   [ -n "$op" ] || { echo "tp: missing operation" >&2; return 2; }
 
+  # Reject blank references before provider discovery or list_issues. Besides
+  # being invalid input, an empty value can equal a provider's missing `key`
+  # field and must never become authority to read or mutate that issue.
+  case "$op" in
+    get_issue|comment|transition)
+      [ "$#" -ge 1 ] || { echo "tp: $op requires a non-blank issue reference" >&2; return 2; }
+      if [[ "$1" =~ ^[[:space:]]*$ ]]; then
+        echo "tp: $op requires a non-blank issue reference" >&2
+        return 2
+      fi
+      ;;
+  esac
+
   local name impl
   name="$(tp_provider_name)"
   impl="$(tp_providers_dir)/${name}.sh"
@@ -96,6 +176,15 @@ tp() {
     return 2
   fi
 
+  case "$op" in
+    get_issue|comment|transition)
+      local reference native_id
+      reference="$1"; shift
+      native_id="$(tp_resolve_issue_reference "$name" "$impl" "$reference")" || return 1
+      set -- "$native_id" "$@"
+      ;;
+  esac
+
   TICKET_PROVIDER="$name" sh "$impl" "$op" "$@"
 }