Sync ako/mxcli: REST request bodies, mapping fidelity, idempotent writes, and platform fixes

.claude/hooks/post-push.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+#
+# PostToolUse hook (Bash) — after a `git push`, report where the branch stands
+# relative to main.
+#
+# Why this exists: twice in one session commits were pushed onto a branch whose
+# pull request had already been merged, and reported as "added to PR #N" when
+# PR #N was closed and contained none of them. A merged PR cannot take new
+# commits, so the work needed a fresh branch and a new PR.
+#
+# It would be better to name the PR directly, but this environment's egress
+# proxy intercepts api.github.com and answers 403 ("GitHub access is not enabled
+# for this session"), so a shell hook cannot ask. What it CAN compute locally is
+# the state both failures shared: the branch was behind origin/main because main
+# had absorbed the branch's earlier commits via the merge.
+#
+# Prints nothing when the branch is simply ahead of main — the normal case —
+# so a clean push stays quiet.
+set -uo pipefail
+
+payload=$(cat)
+
+# Only react to a push. Matched anywhere in the command rather than via the
+# hook's `if` filter, which is a PREFIX match and would miss the common
+# `git add … && git commit … && git push …`.
+command=$(printf '%s' "$payload" | jq -r '.tool_input.command // ""' 2>/dev/null || true)
+case "$command" in
+  *"git push"*) ;;
+  *) exit 0 ;;
+esac
+
+cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then exit 0; fi
+
+# Best effort: a slow or offline fetch must not hold up the session.
+timeout 15 git fetch -q origin main >/dev/null 2>&1 || true
+git rev-parse --verify -q origin/main >/dev/null 2>&1 || exit 0
+
+behind=$(git rev-list --count "HEAD..origin/main" 2>/dev/null || echo 0)
+if [ "$behind" -eq 0 ]; then exit 0; fi
+
+ahead=$(git rev-list --count "origin/main..HEAD" 2>/dev/null || echo 0)
+
+if [ "$ahead" -eq 0 ]; then
+  # Nothing of its own: main has everything this branch has. Either its PR was
+  # merged, or the checkout is stale (an ephemeral container is re-cloned fresh,
+  # so locally-made commits can be absent while the pushed branch still has them).
+  msg="$branch is $behind commit(s) behind origin/main and has none of its own.
+Its pull request may already be merged, or this checkout may be stale — a fresh container
+re-clones the repo, so commits made earlier in the session can be missing locally.
+Check both before describing the branch's state:
+  git log --oneline origin/$branch   (what was actually pushed)
+  restart from main if the PR merged: git checkout -B $branch origin/main"
+else
+  msg="pushed $branch — it is $ahead commit(s) ahead of origin/main but also $behind BEHIND.
+If a pull request from this branch was already merged, it CANNOT carry those $ahead commit(s):
+verify the PR is still open before saying they were added to it.
+If it merged, restart the branch and keep the unmerged work:
+  git fetch origin main && git rebase --onto origin/main <merged-sha> $branch"
+fi
+
+# systemMessage surfaces it to the user; additionalContext puts the same fact in
+# the model's context, which is where the wrong claim was made.
+jq -nc --arg m "$msg" \
+  '{systemMessage: $m, hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $m}}'

.claude/hooks/session-start.sh

@@ -20,13 +20,48 @@ set -euo pipefail
 ANTLR_VERSION='4.13.2'
 ANTLR_TOOLS_VERSION='0.2.2'
 
+cd "${CLAUDE_PROJECT_DIR:-$(dirname "$0")/../..}" 2>/dev/null || exit 0
+
+# 0. Is this checkout what the session thinks it is?
+#
+# The container is ephemeral: it is re-cloned when reprovisioned, so commits made
+# earlier in a session can be absent from the working copy while still present on
+# the remote. That happened twice in one session, and the second time it was
+# misread as a code bug — a grammar rule "missing" from the tree had in fact been
+# committed and pushed hours earlier, and the binary under test was built from
+# the rolled-back tree.
+#
+# Only speaks when the branch is actually behind its own remote, so a healthy
+# start stays silent. Runs before the remote-only exit below because a stale
+# checkout is worth knowing about on any machine.
+_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+if [ -n "${_branch:-}" ] && [ "${_branch}" != "HEAD" ]; then
+  timeout 15 git fetch -q origin "${_branch}" >/dev/null 2>&1 || true
+  if git rev-parse --verify -q "origin/${_branch}" >/dev/null 2>&1; then
+    _behind=$(git rev-list --count "HEAD..origin/${_branch}" 2>/dev/null || echo 0)
+    if [ "${_behind}" -gt 0 ]; then
+      echo "WARNING: HEAD is ${_behind} commit(s) behind origin/${_branch}."
+      echo "  This checkout may be a fresh clone that is missing work pushed earlier."
+      echo "  Reconcile before building or testing:  git log --oneline origin/${_branch}"
+    fi
+  fi
+fi
+
+# The binary carries the commit it was built from (Makefile -X main.Version), so
+# a mismatch means any behaviour observed through bin/mxcli is from other code.
+if [ -x bin/mxcli ]; then
+  _built=$(bin/mxcli --version 2>/dev/null | grep -oE '[0-9a-f]{7,}' | head -1 || true)
+  _head=$(git rev-parse --short HEAD 2>/dev/null || true)
+  if [ -n "${_built:-}" ] && [ -n "${_head:-}" ] && [ "${_built}" != "${_head}" ]; then
+    echo "NOTE: bin/mxcli was built from ${_built}, HEAD is ${_head} — run 'make build' before testing."
+  fi
+fi
+
 # Local (devcontainer / laptop) setups already have these via the Dockerfile.
 if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
   exit 0
 fi
 
-cd "${CLAUDE_PROJECT_DIR:-$(dirname "$0")/../..}"
-
 # 1. ANTLR4 — required by `make grammar`, which `make build` always runs.
 if ! command -v antlr4 >/dev/null 2>&1; then
   echo "Installing antlr4-tools==${ANTLR_TOOLS_VERSION}..."

.claude/settings.json

@@ -9,6 +9,18 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-push.sh",
+            "timeout": 25
+          }
+        ]
+      }
     ]
   }
 }