@delorenj/pjangler 1.2.25 → 1.3.0

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

@@ -137,6 +137,12 @@ already_done() {
 mark_done() {
   touch "$ROLE_DIR/.scripts/.done-$1"
 }
+clear_done() {
+  # Remove only the marker for the explicitly deferred step.  This lets a
+  # later activation reconcile that phase without disturbing completed,
+  # unrelated provisioning state.
+  rm -f -- "$ROLE_DIR/.scripts/.done-$1"
+}
 
 # Fleet source-of-truth (shared across all wrappers/provisioners).
 # Every default below resolves as: env var > fleet.env > config.toml > fallback.
@@ -151,11 +157,12 @@ fi
 unset TELEGRAM_BOT_TOKEN SLACK_BOT_TOKEN SLACK_APP_TOKEN
 
 # Tools we expect on the host
-HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-$(config_get fleet.hermes_bin "$HOME/.hermes/hermes-agent/.venv/bin/hermes")}}"
-HERMES_AGENT_REPO="${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-$(config_get fleet.hermes_repo "$HOME/.hermes/hermes-agent")}}"
+HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-$(config_get fleet.hermes_bin "$HOME/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1/.venv/bin/hermes")}}"
+HERMES_AGENT_REPO="${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-$(config_get fleet.hermes_repo "$HOME/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1")}}"
+PJANGLER_BIN="${PJANGLER_BIN:-$(config_get fleet.pjangler_bin "pj")}"
 HERMES_RUNTIME_GIT_URL="${HERMES_RUNTIME_GIT_URL:-$(config_get fleet.hermes_git_url 'https://github.com/delorenj/hermes-agent.git')}"
-HERMES_RUNTIME_GIT_REF="${HERMES_RUNTIME_GIT_REF:-$(config_get fleet.hermes_git_ref 'feature/PJAN-19-routing-publication')}"
-HERMES_RUNTIME_GIT_SHA="${HERMES_RUNTIME_GIT_SHA:-$(config_get fleet.hermes_git_sha '113e1b182b6d72a7dd02a191f134a41668ceaf0e')}"
+HERMES_RUNTIME_GIT_REF="${HERMES_RUNTIME_GIT_REF:-$(config_get fleet.hermes_git_ref 'main')}"
+HERMES_RUNTIME_GIT_SHA="${HERMES_RUNTIME_GIT_SHA:-$(config_get fleet.hermes_git_sha '0408fec7a153e6c32c064acd2b8053917f1525f1')}"
 HERMES_OAUTH_FILE="${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$(config_get fleet.oauth_file "$HOME/.hermes/auth.json")}}"
 CODEX_HOME="${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$(config_get fleet.codex_home "$HOME/.codex")}}"
 # Prefer a scaffold vendored into this agent directory; fall back to the configured template path.
@@ -197,7 +204,7 @@ BLOODBANK_COMPOSE_DIR="${BLOODBANK_COMPOSE_DIR:-$(config_get bloodbank.compose_d
 PLANE_BASE="${PLANE_BASE:-$(config_get plane.base 'https://plane.delo.sh')}"
 PLANE_API_KEY="${PLANE_API_KEY:-${PLANE_33GOD_API_KEY:-}}"
 
-export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO HERMES_RUNTIME_GIT_URL \
+export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO PJANGLER_BIN HERMES_RUNTIME_GIT_URL \
        HERMES_RUNTIME_GIT_REF HERMES_RUNTIME_GIT_SHA HERMES_OAUTH_FILE CODEX_HOME \
        RUNTIME_SCAFFOLD_DIR REGISTRY_FILE \
        BLOODBANK_NATS_HOST BLOODBANK_NATS_PORT BLOODBANK_COMPOSE_DIR \

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

@@ -12,14 +12,17 @@
 
 [fleet]
 # Absolute path to the shared Hermes executable every agent launcher execs.
-hermes_bin = "~/.hermes/hermes-agent/.venv/bin/hermes"
+hermes_bin = "~/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1/.venv/bin/hermes"
 # Checkout of the shared hermes-agent repo.
-hermes_repo = "~/.hermes/hermes-agent"
+hermes_repo = "~/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1"
+# Canonical CommonProject migration CLI. Runtime provisioning delegates named
+# profile topology to this command; it never rewrites profile links itself.
+pjangler_bin = "pj"
 # Reviewed fleet runtime publication. Provisioning metadata and clean installs
 # must agree on this fork/ref/SHA; do not substitute upstream main.
 hermes_git_url = "https://github.com/delorenj/hermes-agent.git"
-hermes_git_ref = "feature/PJAN-19-routing-publication"
-hermes_git_sha = "113e1b182b6d72a7dd02a191f134a41668ceaf0e"
+hermes_git_ref = "main"
+hermes_git_sha = "0408fec7a153e6c32c064acd2b8053917f1525f1"
 # Fallback runtime scaffold dir — used only when an agent's vendored
 # ./.runtime-scaffold is missing.
 runtime_scaffold_dir = "~/code/hermes-agent-template/runtime-scaffold"

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Secret-free systemd entrypoint. Decrypted values are read only from the
+# service manager's volatile credential directory and never printed or written.
+set -euo pipefail
+
+ROLE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ROLE_YAML="$ROLE_DIR/role.yaml"
+
+yaml_get() {
+  python3 - "$ROLE_YAML" "$1" <<'PYEOF'
+import re, sys
+from pathlib import Path
+text = Path(sys.argv[1]).read_text()
+parts = sys.argv[2].split(".")
+if len(parts) == 2:
+    match = re.search(
+        rf"(?m)^{re.escape(parts[0])}:[ \t]*\n((?:[ \t]+\S.*\n?)*)", text
+    )
+    text = match.group(1) if match else ""
+key = parts[-1]
+match = re.search(rf'(?m)^\s*{re.escape(key)}:\s*"?([^"\n]*)"?\s*$', text)
+print(match.group(1).strip() if match else "")
+PYEOF
+}
+
+AGENT_ID="$(yaml_get agent_id)"
+PROFILE_NAME="$(yaml_get profile)"
+[[ -n "$AGENT_ID" && -n "$PROFILE_NAME" ]] \
+  || { printf 'credential-launch: incomplete role identity\n' >&2; exit 2; }
+[[ -n "${HERMES_BIN:-}" && -x "$HERMES_BIN" ]] \
+  || { printf 'credential-launch: HERMES_BIN is not executable\n' >&2; exit 1; }
+
+mode="${1:-}"
+[[ "$mode" == "gateway" || "$mode" == "heartbeat" ]] \
+  || { printf 'credential-launch: expected gateway or heartbeat\n' >&2; exit 2; }
+
+FLEET_HOME="${HERMES_FLEET_HOME:-$HOME/.hermes}"
+PROFILE_HOME="$FLEET_HOME/profiles/${PROFILE_NAME:-$AGENT_ID}"
+[[ -d "$PROFILE_HOME" && ! -L "$PROFILE_HOME" ]] \
+  || { printf 'credential-launch: named profile is not a real directory\n' >&2; exit 1; }
+export HERMES_HOME="$PROFILE_HOME"
+
+if ! REPO_ROOT="$(git -C "$ROLE_DIR" rev-parse --show-toplevel 2>/dev/null)"; then
+  REPO_ROOT="$ROLE_DIR"
+fi
+export TERMINAL_CWD="$REPO_ROOT"
+
+load_credential() {
+  local credential_id="$1" env_name="$2" credential_file value
+  [[ "$env_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] \
+    || { printf 'credential-launch: invalid credential environment name\n' >&2; exit 2; }
+  credential_file="${CREDENTIALS_DIRECTORY:-}/$credential_id"
+  [[ -n "${CREDENTIALS_DIRECTORY:-}" && -r "$credential_file" ]] || return 0
+  value="$(<"$credential_file")"
+  printf -v "$env_name" '%s' "$value"
+  export "$env_name"
+  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"
+fi
+
+if [[ "$mode" == "heartbeat" ]]; then
+  exec "$ROLE_DIR/.scripts/heartbeat.sh"
+fi
+
+gateway_args=(gateway run --replace)
+MODEL_NAME="$(yaml_get model.name)"
+MODEL_PROVIDER="$(yaml_get model.provider)"
+MODEL_BASE_URL="$(yaml_get model.base_url)"
+MODEL_API_MODE="$(yaml_get model.api_mode)"
+[[ -z "$MODEL_NAME" ]] || gateway_args+=(--model "$MODEL_NAME")
+[[ -z "$MODEL_PROVIDER" ]] || gateway_args+=(--provider "$MODEL_PROVIDER")
+[[ -z "$MODEL_BASE_URL" ]] || gateway_args+=(--base-url "$MODEL_BASE_URL")
+[[ -z "$MODEL_API_MODE" ]] || gateway_args+=(--api-mode "$MODEL_API_MODE")
+[[ -z "$MODEL_KEY_ENV" ]] || gateway_args+=(--key-env "$MODEL_KEY_ENV")
+
+exec "$HERMES_BIN" "${gateway_args[@]}"

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

@@ -15,6 +15,7 @@ set -euo pipefail
 
 ROLE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"   # agents/hermes/<role>
 RUNTIME="$ROLE_DIR/runtime"
+RUN_HOME="${HERMES_HOME:-$RUNTIME}"
 PROMPT_FILE="$ROLE_DIR/.scripts/sentinel.prompt.md"
 STATE_FILE="$RUNTIME/continuous-ticket-sentinel-state.json"
 LOCK_FILE="$RUNTIME/continuous-ticket-sentinel.lock"
@@ -242,7 +243,7 @@ trap 'python3 "$ROLE_DIR/.scripts/momo-wip-lock.py" release "$WIP_LOCK" "hermes:
 
 prompt="$(<"$PROMPT_FILE")"
 set +e
-env HERMES_HOME="$RUNTIME" "$HERMES_BIN" chat -Q --source cron --max-turns 90 -q "$prompt"
+env HERMES_HOME="$RUN_HOME" "$HERMES_BIN" chat -Q --source cron --max-turns 90 -q "$prompt"
 status=$?
 set -e
 

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

@@ -1,10 +1,10 @@
 # shellcheck shell=bash
-# Ticket-provider adapter dispatcher — the single seam between the heartbeat
+# Ticket-provider adapter dispatcher — the single seam between the Scrum Master
 # sentinel engine and a concrete ticket system (Linear | Plane | Trello).
 #
 # The engine NEVER calls a provider directly. It calls `tp <op> [args...]`,
-# which dispatches to providers/<provider>.sh. Swapping providers is a one-line
-# config change in role.yaml (ticket_provider.name) — no engine edits.
+# which dispatches to providers/<provider>.sh. Repo-root .project.json owns the
+# provider/board binding; role.yaml is only a legacy provider-name fallback.
 #
 # Contract (operations every provider must implement):
 #   resolve                       -> JSON {provider, board_id, board_url}
@@ -12,14 +12,22 @@
 #   list_issues                   -> JSON [ {id,key,title,state,state_type,
 #                                            updated_at,assignee,url}, ... ]
 #   get_issue <id>                -> JSON {id,key,title,description,acceptance,
-#                                          state,state_type,comments:[...]}
+#                                          state,state_type,comments:[...],
+#                                          attachments:[...]}
 #   comment <id> <body>           -> prints comment id
 #   transition <id> <normalized>  -> moves issue; normalized in
-#                                     backlog|unstarted|started|in_review|completed
+#                                     backlog|unstarted|started|in_review|completed|
+#                                     cancelled
 #   create_board <name> <id> <d>  -> JSON {board_id, board_url}
+#   create_issue [--if-absent] <title> [desc]
+#                                 -> JSON {issue_id, key, issue_url, created}
+#                                    Files a new ticket on the bound board.
+#                                    NOT idempotent by default (two issues may
+#                                    share a title); --if-absent reuses an exact
+#                                    title match and reports created:false.
 #
 # Each provider reads its credentials from the environment (see providers/*.sh
-# headers) and the board binding from role.yaml under `ticket_provider:`.
+# headers) and the board binding from repo-root .project.json.
 
 # 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 /
@@ -92,7 +100,7 @@ tp() {
 }
 
 # Normalized states the engine reasons in. Adapters map these to provider terms.
-TP_STATES="backlog unstarted started in_review completed"
+TP_STATES="backlog unstarted started in_review completed cancelled"
 
 tp_is_valid_state() {
   case " $TP_STATES " in

package/templates/hermes-agent/template/.scripts/providers/linear.sh

@@ -6,7 +6,8 @@
 #   name: linear
 #   team:    <TEAM_KEY>          e.g. DEL
 #   project: "<Project name>"    optional; scopes milestone/issue queries
-#   state_map: { in_review: "In Review", completed: "Done" }   optional overrides
+#   state_map: { in_review: "In Review", completed: "Done",
+#                cancelled: "Canceled" }   optional overrides
 #
 # Implements the contract in lib/ticket-provider.sh. All Linear access goes
 # through GraphQL so the same envelope works in unattended runs.
@@ -79,6 +80,7 @@ TEAM="$(pj_cfg team)"; [ -n "$TEAM" ] || TEAM="$(tp_cfg team)"
 PROJECT="$(pj_cfg project)"; [ -n "$PROJECT" ] || PROJECT="$(tp_cfg project)"
 SM_IN_REVIEW="$(tp_cfg in_review)"; SM_IN_REVIEW="${SM_IN_REVIEW:-In Review}"
 SM_DONE="$(tp_cfg completed)"; SM_DONE="${SM_DONE:-Done}"
+SM_CANCELLED="$(tp_cfg cancelled)"; SM_CANCELLED="${SM_CANCELLED:-Canceled}"
 
 # All Linear ops require the API key; fail fast and clean before any pipe.
 need_key
@@ -143,6 +145,7 @@ print(json.dumps({"id":i.get("id",""),"key":i.get("identifier",""),"title":i.get
     # Map normalized -> a concrete Linear state name, then resolve its id on the team.
     case "$TARGET" in
       completed)  WANT_TYPE=completed; WANT_NAME="$SM_DONE" ;;
+      cancelled)  WANT_TYPE=canceled;  WANT_NAME="$SM_CANCELLED" ;;
       in_review)  WANT_TYPE=started;   WANT_NAME="$SM_IN_REVIEW" ;;
       started)    WANT_TYPE=started;   WANT_NAME="" ;;
       unstarted)  WANT_TYPE=unstarted; WANT_NAME="" ;;
@@ -172,5 +175,42 @@ print(("ok " + (u.get("issue") or {}).get("identifier","")) if u.get("success")
     exec sh "$0" resolve
     ;;
 
+  create_issue)
+    # File a new issue on the bound team. Team comes from resolved config, never
+    # from an argument. Deliberately NOT idempotent by default: two issues may
+    # legitimately share a title. Pass --if-absent to reuse an issue whose title
+    # already matches instead.
+    IF_ABSENT=0
+    case "${1:-}" in --if-absent) IF_ABSENT=1; shift ;; esac
+    TITLE="${1:?usage: create_issue [--if-absent] <title> [description]}"; DESC="${2:-}"
+    [ -n "$TEAM" ] || die "ticket_provider.team (Linear team key) not set"
+    ISSUE=""; CREATED=true
+    if [ "$IF_ABSENT" = 1 ]; then
+      ISSUE="$(gql 'query($k:String!,$t:String!){ issues(first:1, filter:{team:{key:{eq:$k}}, title:{eq:$t}}){nodes{id identifier url}} }' \
+          "$(python3 -c 'import json,sys; print(json.dumps({"k":sys.argv[1],"t":sys.argv[2]}))' "$TEAM" "$TITLE")" \
+        | python3 -c 'import sys,json
+ns=((json.load(sys.stdin).get("issues") or {}).get("nodes")) or []
+print(json.dumps(ns[0]) if ns else "")')"
+      [ -z "$ISSUE" ] || CREATED=false
+    fi
+    if [ -z "$ISSUE" ]; then
+      TEAM_ID="$(gql 'query($k:String!){ teams(filter:{key:{eq:$k}}){nodes{id}} }' "$(printf '{"k":"%s"}' "$TEAM")" \
+        | python3 -c 'import sys,json
+ns=((json.load(sys.stdin).get("teams") or {}).get("nodes")) or []
+print(ns[0].get("id","") if ns else "")')"
+      [ -n "$TEAM_ID" ] || die "no Linear team with key '$TEAM'"
+      ISSUE="$(gql 'mutation($team:String!,$t:String!,$d:String){ issueCreate(input:{teamId:$team,title:$t,description:$d}){ success issue{id identifier url} } }' \
+          "$(python3 -c 'import json,sys; print(json.dumps({"team":sys.argv[1],"t":sys.argv[2],"d":sys.argv[3] or None}))' "$TEAM_ID" "$TITLE" "$DESC")" \
+        | python3 -c 'import sys,json
+r=json.load(sys.stdin).get("issueCreate") or {}
+print(json.dumps(r["issue"]) if r.get("success") and r.get("issue") else "")')"
+    fi
+    [ -n "$ISSUE" ] || die "create_issue failed"
+    printf '%s' "$ISSUE" | CREATED="$CREATED" python3 -c 'import sys,json,os
+i=json.load(sys.stdin)
+print(json.dumps({"issue_id":i.get("id",""),"key":i.get("identifier",""),
+                  "issue_url":i.get("url",""),"created":os.environ["CREATED"]=="true"}))'
+    ;;
+
   *) die "unknown op: $OP" ;;
 esac

package/templates/hermes-agent/template/.scripts/providers/plane.sh

@@ -1,13 +1,13 @@
 #!/usr/bin/env sh
 # Plane ticket-provider adapter.
 #
-# Credentials:  PLANE_API_KEY   (X-API-Key header)
+# Credentials:  PLANE_API_KEY or PLANE_<WORKSPACE>_API_KEY (X-API-Key header)
 # Endpoint:     PLANE_BASE       (default https://plane.delo.sh)
-# Board binding (role.yaml `ticket_provider:`):
-#   name: plane
+# Board binding (repo-root .project.json `ticket_provider:`):
 #   workspace: <workspace-slug>      (or env PLANE_WORKSPACE)
-#   project:   <project-uuid>        (set by create_board / 42-ticket-provider)
-#   state_map: { in_review: "In Review", completed: "Done" }   optional
+#   board_id:  <project-uuid>        (set by create_board / 42-ticket-provider)
+#   state_map: { in_review: "In Review", completed: "Done",
+#                cancelled: "Cancelled" }   optional
 #
 # Plane model:  project = board, cycle = milestone, state.group in
 #   backlog|unstarted|started|completed|cancelled.
@@ -21,9 +21,44 @@ ROLE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 ROLE_YAML="$ROLE_DIR/role.yaml"
 BASE="${PLANE_BASE:-https://plane.delo.sh}"
 
+FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
+
 die() { echo "plane: $*" >&2; exit 1; }
 need_key() { [ -n "${PLANE_API_KEY:-}" ] || die "PLANE_API_KEY is not set"; }
 
+workspace_key() {
+  key="$(printf '%s' "${1:-default}" | tr '[:lower:]' '[:upper:]' | sed 's/[^A-Z0-9]/_/g')"
+  [ -n "$key" ] || key="DEFAULT"
+  printf 'PLANE_%s_API_KEY' "$key"
+}
+
+# dotenv_value FILE KEY — read one exact dotenv assignment as inert data.
+# Never source the shared fleet file: it may contain unrelated command
+# substitutions or credential helpers that this provider must not execute.
+dotenv_value() {
+  python3 - "$1" "$2" <<'PY'
+import pathlib, sys
+
+path = pathlib.Path(sys.argv[1])
+key = sys.argv[2]
+value = ""
+for raw in path.read_text(encoding="utf-8").splitlines():
+    line = raw.strip()
+    if not line or line.startswith("#"):
+        continue
+    if line.startswith("export "):
+        line = line[7:].lstrip()
+    name, sep, candidate = line.partition("=")
+    if sep and name.strip() == key:
+        candidate = candidate.strip()
+        if len(candidate) >= 2 and candidate[0] == candidate[-1] and candidate[0] in "'\"":
+            candidate = candidate[1:-1]
+        value = candidate
+        break
+print(value, end="")
+PY
+}
+
 tp_cfg() {
   [ -f "$ROLE_YAML" ] || return 0
   python3 - "$ROLE_YAML" "$1" <<'PY'
@@ -54,13 +89,23 @@ else:
 PY
 }
 
-# Board binding: .project.json (SOT) first, then role.yaml, then env.
+# Board binding: .project.json (SOT) first, then legacy role.yaml, then env.
 WS="$(pj_cfg workspace)"; [ -n "$WS" ] || WS="$(tp_cfg workspace)"; WS="${WS:-${PLANE_WORKSPACE:-}}"
-PROJ="$(pj_cfg board_id)"; [ -n "$PROJ" ] || PROJ="$(tp_cfg project)"
+PROJ="$(pj_cfg board_id)"; [ -n "$PROJ" ] || PROJ="$(tp_cfg project)"; [ -n "$PROJ" ] || PROJ="$(tp_cfg board_id)"
 SM_IN_REVIEW="$(tp_cfg in_review)"; SM_IN_REVIEW="${SM_IN_REVIEW:-In Review}"
 SM_DONE="$(tp_cfg completed)"; SM_DONE="${SM_DONE:-Done}"
+SM_CANCELLED="$(tp_cfg cancelled)"; SM_CANCELLED="${SM_CANCELLED:-Cancelled}"
 API="$BASE/api/v1/workspaces/$WS"
 
+if [ -z "${PLANE_API_KEY:-}" ]; then
+  KEY="$(workspace_key "$WS")"
+  eval "PLANE_API_KEY=\${$KEY:-}"
+  if [ -z "${PLANE_API_KEY:-}" ] && [ -f "$FLEET_ENV" ]; then
+    PLANE_API_KEY="$(dotenv_value "$FLEET_ENV" "$KEY")"
+  fi
+  export PLANE_API_KEY
+fi
+
 # api METHOD PATH [JSON_BODY] — call Plane REST, print response body.
 api() {
   need_key
@@ -68,9 +113,12 @@ api() {
   if [ -n "$body" ]; then
     curl -fsS -X "$method" "$API/$path" \
       -H "X-API-Key: $PLANE_API_KEY" -H "Content-Type: application/json" \
+      -H "User-Agent: curl/8.0" \
       -d "$body"
   else
-    curl -fsS -X "$method" "$API/$path" -H "X-API-Key: $PLANE_API_KEY"
+    curl -fsS -X "$method" "$API/$path" \
+      -H "X-API-Key: $PLANE_API_KEY" \
+      -H "User-Agent: curl/8.0"
   fi
 }
 
@@ -80,6 +128,7 @@ resolve_state_id() {
   [ -n "$PROJ" ] || die "ticket_provider.project not set"
   case "$want" in
     completed) grp=completed; nm="$SM_DONE" ;;
+    cancelled) grp=cancelled; nm="$SM_CANCELLED" ;;
     in_review) grp=started;   nm="$SM_IN_REVIEW" ;;
     started)   grp=started;   nm="" ;;
     unstarted) grp=unstarted; nm="" ;;
@@ -87,7 +136,7 @@ resolve_state_id() {
     *) die "invalid normalized state: $want" ;;
   esac
   api GET "projects/$PROJ/states/" | GRP="$grp" NM="$nm" python3 -c 'import sys,json,os
-d=json.load(sys.stdin); rows=d.get("results", d if isinstance(d,list) else [])
+d=json.load(sys.stdin); rows=d if isinstance(d,list) else d.get("results", []) if isinstance(d,dict) else []
 grp=os.environ["GRP"]; nm=os.environ.get("NM","")
 named=[s for s in rows if nm and (s.get("name","").lower()==nm.lower())]
 grouped=[s for s in rows if s.get("group")==grp]
@@ -100,8 +149,8 @@ need_key
 
 case "$OP" in
   resolve)
-    [ -n "$WS" ] || die "workspace not set (role.yaml ticket_provider.workspace or PLANE_WORKSPACE)"
-    [ -n "$PROJ" ] || die "project not set (run 42-ticket-provider.sh)"
+    [ -n "$WS" ] || die "workspace not set (.project.json ticket_provider.workspace or PLANE_WORKSPACE)"
+    [ -n "$PROJ" ] || die "project not set (.project.json ticket_provider.board_id; run 42-ticket-provider.sh)"
     printf '{"provider":"plane","board_id":"%s","board_url":"%s/%s/projects/%s/issues/"}\n' \
       "$PROJ" "$BASE" "$WS" "$PROJ"
     ;;
@@ -109,7 +158,7 @@ case "$OP" in
   active_milestone)
     [ -n "$PROJ" ] || die "project not set"
     api GET "projects/$PROJ/cycles/" | python3 -c 'import sys,json,datetime
-d=json.load(sys.stdin); rows=d.get("results", d if isinstance(d,list) else [])
+d=json.load(sys.stdin); rows=d if isinstance(d,list) else d.get("results", []) if isinstance(d,dict) else []
 now=datetime.datetime.now(datetime.timezone.utc)
 def cur(c):
     s,e=c.get("start_date"),c.get("end_date")
@@ -126,9 +175,9 @@ print(json.dumps({"id":m.get("id",""),"name":m.get("name",""),"state":"active" i
     ISSUES="$(api GET "projects/$PROJ/issues/")"
     printf '%s\n%s\n' "$STATES" "$ISSUES" | BASE="$BASE" WS="$WS" PROJ="$PROJ" python3 -c 'import sys,json,os
 parts=sys.stdin.read().split("\n",1)
-srows=json.loads(parts[0] or "{}"); srows=srows.get("results", srows if isinstance(srows,list) else [])
+srows=json.loads(parts[0] or "{}"); srows=srows if isinstance(srows,list) else srows.get("results", []) if isinstance(srows,dict) else []
 smap={s.get("id"):(s.get("name",""),s.get("group","")) for s in srows}
-d=json.loads(parts[1] or "{}"); rows=d.get("results", d if isinstance(d,list) else [])
+d=json.loads(parts[1] or "{}"); rows=d if isinstance(d,list) else d.get("results", []) if isinstance(d,dict) else []
 base,ws,proj=os.environ["BASE"],os.environ["WS"],os.environ["PROJ"]
 out=[]
 for n in rows:
@@ -146,19 +195,30 @@ print(json.dumps(out))'
     STATES="$(api GET "projects/$PROJ/states/")"
     ISSUE="$(api GET "projects/$PROJ/issues/$ID/")"
     COMM="$(api GET "projects/$PROJ/issues/$ID/comments/" 2>/dev/null || echo '[]')"
-    printf '%s\n%s\n%s\n' "$STATES" "$ISSUE" "$COMM" | python3 -c 'import sys,json,re
-parts=sys.stdin.read().split("\n",2)
-srows=json.loads(parts[0] or "{}"); srows=srows.get("results", srows if isinstance(srows,list) else [])
+    ATTACH="$(api GET "projects/$PROJ/issues/$ID/issue-attachments/" 2>/dev/null || echo '[]')"
+    printf '%s\n%s\n%s\n%s\n' "$STATES" "$ISSUE" "$COMM" "$ATTACH" | python3 -c 'import sys,json,re
+parts=sys.stdin.read().split("\n",3)
+srows=json.loads(parts[0] or "{}"); srows=srows if isinstance(srows,list) else srows.get("results", []) if isinstance(srows,dict) else []
 smap={s.get("id"):(s.get("name",""),s.get("group","")) for s in srows}
-i=json.loads(parts[1] or "{}"); c=json.loads(parts[2] or "[]")
-rows=c.get("results", c if isinstance(c,list) else [])
+i=json.loads(parts[1] or "{}"); c=json.loads(parts[2] or "[]"); a=json.loads(parts[3] or "[]")
+rows=c if isinstance(c,list) else c.get("results", []) if isinstance(c,dict) else []
+arows=a if isinstance(a,list) else a.get("results", []) if isinstance(a,dict) else []
 def strip(h): return re.sub(r"<[^>]+>","",h or "").strip()
 name,group=smap.get(i.get("state",""),("",""))
 desc=strip(i.get("description_html",""))
 cs=[{"id":x.get("id",""),"body":strip(x.get("comment_html","")),"author":""} for x in rows]
+ats=[]
+for x in arows:
+    attrs=x.get("attributes") or {}
+    ats.append({"id":x.get("id",""),"name":attrs.get("name",x.get("name","")),
+                "type":attrs.get("type",x.get("type","")),
+                "size":attrs.get("size",x.get("size",0)),"asset":x.get("asset",""),
+                "url":x.get("asset_url",x.get("url","")),
+                "created_at":x.get("created_at",""),"updated_at":x.get("updated_at",""),
+                "is_uploaded":x.get("is_uploaded",False)})
 print(json.dumps({"id":i.get("id",""),"key":i.get("sequence_id",""),"title":i.get("name",""),
                   "description":desc,"acceptance":desc,
-                  "state":name,"state_type":group,"comments":cs}))'
+                  "state":name,"state_type":group,"comments":cs,"attachments":ats}))'
     ;;
 
   comment)
@@ -180,7 +240,7 @@ print(json.dumps({"id":i.get("id",""),"key":i.get("sequence_id",""),"title":i.ge
     NAME="${1:?usage: create_board <name> <ident> <desc>}"; IDENT="${2:-}"; DESC="${3:-}"
     [ -n "$WS" ] || die "workspace not set"
     EXIST="$(api GET "projects/?per_page=200" | NAME="$NAME" IDENT="$IDENT" python3 -c 'import sys,json,os
-d=json.load(sys.stdin); rows=d.get("results", d if isinstance(d,list) else [])
+d=json.load(sys.stdin); rows=d if isinstance(d,list) else d.get("results", []) if isinstance(d,dict) else []
 name=os.environ["NAME"].strip().lower(); ident=os.environ["IDENT"].upper()
 # Repo NAME is the primary key — links an existing repo board even if its
 # identifier differs (Plane does not enforce unique names, so this prevents
@@ -198,5 +258,41 @@ print(pid)')"
     printf '{"board_id":"%s","board_url":"%s/%s/projects/%s/issues/"}\n' "$PID" "$BASE" "$WS" "$PID"
     ;;
 
+  create_issue)
+    # File a new ticket on the bound board. Board/workspace come from resolved
+    # config, never from an argument. Deliberately NOT idempotent by default:
+    # two issues may legitimately share a title. Pass --if-absent to reuse an
+    # issue whose title already matches exactly (case-insensitive) instead.
+    IF_ABSENT=0
+    case "${1:-}" in --if-absent) IF_ABSENT=1; shift ;; esac
+    TITLE="${1:?usage: create_issue [--if-absent] <title> [description]}"; DESC="${2:-}"
+    [ -n "$WS" ] || die "workspace not set (.project.json ticket_provider.workspace or PLANE_WORKSPACE)"
+    [ -n "$PROJ" ] || die "project not set (.project.json ticket_provider.board_id; run 42-ticket-provider.sh)"
+    IID=""; SEQ=""; CREATED=true
+    if [ "$IF_ABSENT" = 1 ]; then
+      HIT="$(api GET "projects/$PROJ/issues/?per_page=200" | TITLE="$TITLE" python3 -c 'import sys,json,os
+d=json.load(sys.stdin); rows=d if isinstance(d,list) else d.get("results", []) if isinstance(d,dict) else []
+want=os.environ["TITLE"].strip().lower()
+m=next((i for i in rows if (i.get("name") or "").strip().lower()==want), None)
+print((str(m.get("id","")) + " " + str(m.get("sequence_id","") or "")) if m else "")')"
+      if [ -n "$HIT" ]; then IID="${HIT%% *}"; SEQ="${HIT#* }"; CREATED=false; fi
+    fi
+    if [ -z "$IID" ]; then
+      NEW="$(api POST "projects/$PROJ/issues/" \
+        "$(python3 -c 'import html,json,sys
+body={"name": sys.argv[1]}
+desc=sys.argv[2]
+if desc: body["description_html"]="<p>"+html.escape(desc)+"</p>"
+print(json.dumps(body))' "$TITLE" "$DESC")" \
+        | python3 -c 'import sys,json
+d=json.load(sys.stdin)
+print(str(d.get("id","")) + " " + str(d.get("sequence_id","") or ""))')"
+      IID="${NEW%% *}"; SEQ="${NEW#* }"
+    fi
+    [ -n "$IID" ] || die "create_issue failed"
+    printf '{"issue_id":"%s","key":"%s","issue_url":"%s/%s/projects/%s/issues/%s","created":%s}\n' \
+      "$IID" "$SEQ" "$BASE" "$WS" "$PROJ" "$IID" "$CREATED"
+    ;;
+
   *) die "unknown op: $OP" ;;
 esac

package/templates/hermes-agent/template/.scripts/providers/trello.sh

@@ -6,7 +6,8 @@
 #   name: trello
 #   board: <board-id>                 (set by create_board / 42-ticket-provider)
 #   state_map: { backlog:"Backlog", unstarted:"To Do", started:"In Progress",
-#                in_review:"Review", completed:"Done" }   optional
+#                in_review:"Review", completed:"Done", cancelled:"Cancelled" }
+#                                              optional
 #
 # Trello model:  board = project & milestone, list = state, card = issue.
 # Trello has no milestone primitive, so active_milestone returns the board.
@@ -61,6 +62,7 @@ list_name_for() {
     started)   v="$(tp_cfg started)";   printf '%s' "${v:-In Progress}" ;;
     in_review) v="$(tp_cfg in_review)"; printf '%s' "${v:-Review}" ;;
     completed) v="$(tp_cfg completed)"; printf '%s' "${v:-Done}" ;;
+    cancelled) v="$(tp_cfg cancelled)"; printf '%s' "${v:-Cancelled}" ;;
     *) die "invalid normalized state: $1" ;;
   esac
 }
@@ -156,5 +158,36 @@ print(next((b["id"] for b in rows if b.get("name","").lower()==nm), ""))')"
 b=json.load(sys.stdin); print(json.dumps({"board_id":os.environ["BID"],"board_url":b.get("url","")}))'
     ;;
 
+  create_issue)
+    # File a new card on the bound board. Board comes from resolved config,
+    # never from an argument. Deliberately NOT idempotent by default: two cards
+    # may legitimately share a title. Pass --if-absent to reuse a card whose
+    # name already matches exactly (case-insensitive) instead.
+    IF_ABSENT=0
+    case "${1:-}" in --if-absent) IF_ABSENT=1; shift ;; esac
+    TITLE="${1:?usage: create_issue [--if-absent] <title> [description]}"; DESC="${2:-}"
+    [ -n "$BOARD" ] || die "board not set (run 42-ticket-provider.sh)"
+    CID=""; CREATED=true
+    if [ "$IF_ABSENT" = 1 ]; then
+      CID="$(api GET "boards/$BOARD/cards" "fields=name" | NM="$TITLE" python3 -c 'import sys,json,os
+rows=json.load(sys.stdin); nm=os.environ["NM"].strip().lower()
+print(next((c["id"] for c in rows if (c.get("name") or "").strip().lower()==nm), ""))')"
+      [ -z "$CID" ] || CREATED=false
+    fi
+    if [ -z "$CID" ]; then
+      # New cards land in the backlog list, falling back to the unstarted one.
+      LID="$(list_id_for backlog)"
+      [ -n "$LID" ] || LID="$(list_id_for unstarted)"
+      [ -n "$LID" ] || die "no Trello list mapped for 'backlog' or 'unstarted' (check state_map)"
+      CID="$(api POST "cards" "idList=$LID&name=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$TITLE")&desc=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$DESC")" \
+        | python3 -c 'import sys,json; print(json.load(sys.stdin).get("id",""))')"
+    fi
+    [ -n "$CID" ] || die "create_issue failed"
+    api GET "cards/$CID" "fields=url,shortLink" | CID="$CID" CREATED="$CREATED" python3 -c 'import sys,json,os
+c=json.load(sys.stdin)
+print(json.dumps({"issue_id":os.environ["CID"],"key":c.get("shortLink",""),
+                  "issue_url":c.get("url",""),"created":os.environ["CREATED"]=="true"}))'
+    ;;
+
   *) die "unknown op: $OP" ;;
 esac