feat(issue-21): persist and forward the control-plane binding in create/resume/stop; status and reconcile honor MAM_JOBS_DIR

A session row now records the control plane it belongs to, and the pane gets it explicitly instead of relying on env inheritance. - lib_py/control_plane.py (+ thin lib.sh wrappers mam_control_plane_json / mam_control_plane_prefix): the binding is WORKSPACE_ROOT, AGENT_SESSIONS_YAML, MAM_JOBS_DIR, DELEGATE_JOB_LOGS_DIR as absolute paths. - create: the binding is always persisted on the row (`control_plane`) and forwarded to the pane only when it differs from what --workspace alone implies, as leading K=V tokens that lib.sh's new-session already turns into --env (fresh pane) or `env K=V` (reused idle pane). pane.cmd_full and start_command stay unprefixed. A binding with whitespace that would have to be forwarded is refused with exit 2 (lib.sh splits the flags unquoted); the ~/.local/bin wrapper path records the binding but warns it is not forwarded. - resume: the row's binding wins over the caller's env (a difference is reported on stderr) and is forwarded again; a legacy row without one uses the caller's binding and update_yaml_resumed.sh records it. - stop: registry order MAM_JOBS_DIR > the row's mam_jobs_dir > $WORKSPACE_ROOT/.mam/jobs > .mam/jobs, exported for delegate_publish_event. - status: both get_job_status copies look in MAM_JOBS_DIR, the row's registry and the matching audit logs before the old candidates. - reconcile: MAM_JOBS_DIR wins in the subscribe heredoc and is passed in. Tests T3-0..T3-8 (mock herdr: forwarding is verified at the herdr-call level only; real pane env propagation is left to item 7). T3-7 is a static guard. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017R3Eg7MEpSWnm1oB9ZPP6G
2026-09-14 03:34:48 +00:00
1 parent d907359746
commit ee1d8966c1
@@ -2693,3 +2693,19 @@ handle_startup_dialogs() {

 # Auto-initialize the herdr translation shim wrapper on library source
 _init_herdr_isolation
+
+# ---------------------------------------------------------------------------
+# Issue #21 (item 3): control-plane binding of a session row. The logic lives
+# in lib_py/control_plane.py; these are thin shell entry points.
+# mam_control_plane_json <workspace> [<row control_plane JSON>]
+mam_control_plane_json() {
+  PYTHONPATH="$SKILL_DIR:${PYTHONPATH:-}" "$(_delegate_py_bin)" -m lib_py.control_plane json "$@"
+}
+
+# mam_control_plane_prefix <json>: the leading K=V tokens for new-session, or
+# nothing when no forward is needed. rc 3: a forward is needed but a path
+# contains whitespace (lib.sh splits the --env flags unquoted).
+mam_control_plane_prefix() {
+  [ -n "${1:-}" ] || return 0
+  PYTHONPATH="$SKILL_DIR:${PYTHONPATH:-}" "$(_delegate_py_bin)" -m lib_py.control_plane prefix "$1"
+}
@@ -0,0 +1,95 @@
+"""Control-plane binding of a session row (Issue #21, item 3).
+
+The binding is the four absolute paths a session's tools must agree on:
+WORKSPACE_ROOT, AGENT_SESSIONS_YAML, MAM_JOBS_DIR, DELEGATE_JOB_LOGS_DIR.
+create/resume persist it on the row (`control_plane`) and forward it to the
+pane only when it differs from what `--workspace` alone would imply, through
+the leading `K=V` tokens lib.sh's new-session already turns into `--env`.
+
+CLI (used by lib.sh):
+  python -m lib_py.control_plane json <workspace> [<row control_plane JSON>]
+      -> {4 keys, "forward": bool, "whitespace": bool, "source": "row"|"env"}
+  python -m lib_py.control_plane prefix <json>
+      -> "WORKSPACE_ROOT=... AGENT_SESSIONS_YAML=... ... " or "" (no forward)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sys
+from typing import Dict, Optional
+
+KEYS = ("workspace_root", "agent_sessions_yaml", "mam_jobs_dir", "delegate_job_logs_dir")
+ENV = {"workspace_root": "WORKSPACE_ROOT", "agent_sessions_yaml": "AGENT_SESSIONS_YAML",
+       "mam_jobs_dir": "MAM_JOBS_DIR", "delegate_job_logs_dir": "DELEGATE_JOB_LOGS_DIR"}
+
+
+def _abs(p: str) -> str:
+    return os.path.realpath(os.path.expanduser(p))
+
+
+def defaults(workspace: str) -> Dict[str, str]:
+    """D(ws): the binding `--workspace` implies on its own."""
+    ws = _abs(workspace)
+    mam = os.path.join(ws, ".mam")
+    return {"workspace_root": ws, "agent_sessions_yaml": os.path.join(mam, "agent-sessions.yaml"),
+            "mam_jobs_dir": os.path.join(mam, "jobs"), "delegate_job_logs_dir": os.path.join(mam, "delegate_job_logs")}
+
+
+def from_env(env=None) -> Dict[str, str]:
+    env = os.environ if env is None else env
+    b = defaults(env.get("WORKSPACE_ROOT") or os.getcwd())
+    for k, var in ENV.items():
+        v = (env.get(var) or "").strip()
+        if v:
+            b[k] = _abs(v)
+    return b
+
+
+def describe(workspace: str, row: Optional[dict] = None) -> dict:
+    """The binding to use: the row's persisted one if complete (D11), else the
+    caller's env. A row binding that differs from the env is reported on stderr."""
+    env_b = from_env()
+    source = "env"
+    b = env_b
+    if isinstance(row, dict) and all(isinstance(row.get(k), str) and row.get(k) for k in KEYS):
+        b = {k: row[k] for k in KEYS}
+        source = "row"
+        if b != env_b:
+            print("WARNING: using the control-plane binding recorded in the row "
+                  f"({json.dumps(b, sort_keys=True)}) instead of the caller's environment", file=sys.stderr)
+    return {**b, "forward": b != defaults(workspace),
+            "whitespace": any(any(c.isspace() for c in v) for v in b.values()), "source": source}
+
+
+def prefix(desc: dict) -> str:
+    if not desc.get("forward"):
+        return ""
+    return "".join(f"{ENV[k]}={shlex.quote(desc[k])} " for k in KEYS)
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if len(argv) >= 2 and argv[0] == "json":
+        row = None
+        if len(argv) >= 3 and argv[2].strip():
+            try:
+                row = json.loads(argv[2])
+            except json.JSONDecodeError:
+                row = None
+        print(json.dumps(describe(argv[1], row)))
+        return 0
+    if len(argv) == 2 and argv[0] == "prefix":
+        desc = json.loads(argv[1])
+        if desc.get("forward") and desc.get("whitespace"):
+            return 3  # lib.sh splits --env flags unquoted: refuse rather than break silently
+        sys.stdout.write(prefix(desc))
+        return 0
+    print(__doc__, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -202,6 +202,22 @@ if [ -z "$CMD_FULL" ]; then
  esac
 fi

+# Issue #21 (item 3): the control-plane binding. Persisted on the row always;
+# forwarded to the pane (leading K=V tokens that lib.sh's new-session turns
+# into --env) only when it differs from what --workspace alone implies.
+# lib.sh splits those flags unquoted (and the idle-pane path evals them), so a
+# binding with whitespace that would have to be forwarded is refused.
+CP_JSON="$(mam_control_plane_json "$WORKSPACE" 2>/dev/null || true)"
+CP_PREFIX=""
+if [ -n "$CP_JSON" ]; then
+  cp_rc=0
+  CP_PREFIX="$(mam_control_plane_prefix "$CP_JSON")" || cp_rc=$?
+  if [ "$cp_rc" -eq 3 ]; then
+    echo "ERROR: control-plane path contains whitespace; cannot forward to the pane" >&2
+    exit 2
+  fi
+fi
+
 spawn() {
  if [ -z "$HERDR_SERVER_OPT" ]; then
    if [ -z "${HERDR_SESSION_NAME:-}" ] || [ "$HERDR_SESSION_NAME" = "default" ]; then
@@ -213,20 +229,21 @@ spawn() {
      if { [ -x "$WRAPPER" ] && [ "$(basename "$WRAPPER")" != "claude" ]; } || [ "$USE_WRAPPER" = "1" ]; then
        SESSION_UUID=""
        CMD_FULL="$("$(_delegate_py_bin)" -m lib_py.agents spawn-spec "$AGENT" "$RESOLVED_BIN" "" "true" 2>/dev/null || echo "${RESOLVED_BIN} --dangerously-skip-permissions")"
+        [ -z "$CP_PREFIX" ] || echo "WARNING: the ~/.local/bin wrapper path bypasses herdr; the control-plane binding is recorded but not forwarded" >&2
        nohup "$WRAPPER" >/dev/null 2>&1 &
        disown
      else
-        HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CMD_FULL"
+        HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
      fi
      ;;
    agy|hermes|grok|codex)
-      HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CMD_FULL"
+      HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
      ;;
    opencode)
      if [ -z "${OPENCODE_PERMISSION:-}" ]; then
        export OPENCODE_PERMISSION='{"*":"allow"}'
      fi
-      HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CMD_FULL"
+      HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
      ;;
    *) echo "ERROR: --agent must be claude, agy, hermes, grok, opencode, or codex, got: $AGENT" >&2; exit 2 ;;
  esac
@@ -391,7 +408,7 @@ atomic_dump_yaml "$AGENT_SESSIONS_YAML" \
  MAM_WS_LABEL="$MAM_WS_LABEL" \
  SESSION_UUID="$SESSION_UUID" \
  LAST_VISIBLE_STATUS_OVERRIDE="${LAST_VISIBLE_STATUS_OVERRIDE:-}" \
-  DELEGATE_JOB_ID="$DELEGATE_JOB_ID" ROLE="$ROLE" <<'PYEOF'
+  DELEGATE_JOB_ID="$DELEGATE_JOB_ID" ROLE="$ROLE" CONTROL_PLANE_JSON="$CP_JSON" <<'PYEOF'
 name = os.environ['SESSION_NAME']
 agent = os.environ['AGENT']
 role = os.environ['ROLE']
@@ -487,6 +504,15 @@ last_vis_override = os.environ.get('LAST_VISIBLE_STATUS_OVERRIDE', '')
 if last_vis_override:
    entry['last_visible_status'] = last_vis_override

+# Issue #21: the control-plane binding this row was created against.
+_cp_raw = os.environ.get('CONTROL_PLANE_JSON', '')
+if _cp_raw:
+    try:
+        import json as _json
+        _cp = _json.loads(_cp_raw)
+        entry['control_plane'] = {k: _cp[k] for k in ('workspace_root', 'agent_sessions_yaml', 'mam_jobs_dir', 'delegate_job_logs_dir')}
+    except Exception:
+        pass
 sessions.append(entry)

 snap = d.setdefault('snapshot', {})
@@ -100,7 +100,7 @@ if [ "$SUBSCRIBE" = "1" ]; then
  # The MQTT subscribe loop exits 3 to signal "broker unavailable → poll instead".
  set +e
  YAML_PATH="$AGENT_SESSIONS_YAML" HOME_DIR="$HOME_DIR" CLAUDE_PROJECT_DIR="$CLAUDE_PROJECT_DIR" LOCAL_BIN="$LOCAL_BIN" \
-    WORKSPACE_ROOT="$WORKSPACE_ROOT" SUB_TIMEOUT="$SUB_TIMEOUT" SUB_IDLE_TIMEOUT="$SUB_IDLE_TIMEOUT" \
+    WORKSPACE_ROOT="$WORKSPACE_ROOT" MAM_JOBS_DIR="${MAM_JOBS_DIR:-}" SUB_TIMEOUT="$SUB_TIMEOUT" SUB_IDLE_TIMEOUT="$SUB_IDLE_TIMEOUT" \
    SKILLS_DIR="$SKILLS_DIR" LIB_SH="$LIB_SH" \
    "$PYBIN" - <<'PYEOF' &
 import os, sys, json, time, subprocess
@@ -236,7 +236,9 @@ def on_message(_client, _userdata, msg):
        if not jid or not event:
            return
        
-        if workspace_root:
+        if os.environ.get('MAM_JOBS_DIR'):
+            registry_dir = os.environ['MAM_JOBS_DIR']  # Issue #21: MAM_JOBS_DIR wins
+        elif workspace_root:
            registry_dir = os.path.join(workspace_root, '.mam', 'jobs')
        else:
            yaml_dir = os.path.dirname(yaml_path) if yaml_path else ""
@@ -150,6 +150,29 @@ else
  fi
 fi

+# Issue #21 (item 3, D11): the control-plane binding recorded on the row wins
+# over the caller's environment (a difference is reported on stderr); a legacy
+# row without one uses the caller's binding, which update_yaml_resumed.sh then
+# records. Forwarded to the pane only when it differs from --workspace's own.
+ROW_CP="$(MAM_STATE_JSON="$(load_state_json)" SESSION_NAME="$SESSION_NAME" python3 -c "
+import json, os
+d = json.loads(os.environ.get('MAM_STATE_JSON') or '{}')
+for s in d.get('herdr_sessions', []):
+    if s.get('name') == os.environ['SESSION_NAME'] and isinstance(s.get('control_plane'), dict):
+        print(json.dumps(s['control_plane']))
+        break
+" 2>/dev/null || true)"
+CP_JSON="$(mam_control_plane_json "$WORKSPACE" "$ROW_CP" || true)"
+CP_PREFIX=""
+if [ -n "$CP_JSON" ]; then
+  cp_rc=0
+  CP_PREFIX="$(mam_control_plane_prefix "$CP_JSON")" || cp_rc=$?
+  if [ "$cp_rc" -eq 3 ]; then
+    echo "ERROR: control-plane path contains whitespace; cannot forward to the pane" >&2
+    exit 2
+  fi
+fi
+
 if [ "${DRY_RUN:-0}" = "1" ]; then
  echo "[dry-run] would spawn: $CMD_FULL"
  exit 0
@@ -162,7 +185,7 @@ if [ "$AGENT" = "opencode" ]; then
 fi

 # 4. Spawn new agent session (delegates to herdr translation shim)
-_herdr new-session -d -s "$SESSION_NAME" -c "$WORKSPACE" "$CMD_FULL"
+_herdr new-session -d -s "$SESSION_NAME" -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
 if [ "$AGENT" = "claude" ]; then
  # auto-handle trust / bypass dialogs
  handle_startup_dialogs "$SESSION_NAME" 20
@@ -172,7 +195,7 @@ fi
 sleep 2

 # 5. Update agent-sessions.yaml: status running, last_visible_status
-bash "$(dirname "${BASH_SOURCE[0]}")/update_yaml_resumed.sh" \
+CONTROL_PLANE_JSON="$CP_JSON" bash "$(dirname "${BASH_SOURCE[0]}")/update_yaml_resumed.sh" \
  --session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT" --workspace "$WORKSPACE" \
  --herdr-session "$HERDR_SESSION_NAME" --cmd-full "$CMD_FULL" \
  ${HERDR_WORKSPACE_OPT:+--herdr-workspace "$HERDR_WORKSPACE_OPT"}
@@ -163,6 +163,16 @@ else:
        target['herdr_workspace'] = wsl

 target['status'] = 'running'
+# Issue #21 (D11): a row keeps the control-plane binding it was created with;
+# a legacy row without one gets the binding this resume used.
+_cp_raw = os.environ.get('CONTROL_PLANE_JSON', '')
+if _cp_raw and not isinstance(target.get('control_plane'), dict):
+    try:
+        import json as _json
+        _cp = _json.loads(_cp_raw)
+        target['control_plane'] = {k: _cp[k] for k in ('workspace_root', 'agent_sessions_yaml', 'mam_jobs_dir', 'delegate_job_logs_dir')}
+    except Exception:
+        pass
 if not uuid:
    # ISSUE-3 (challenge c4b0a075): a Class A fresh-spawn resume re-arms
    # discovery from scratch - the resumed agent has not spoken yet, so any
@@ -160,7 +160,14 @@ def get_job_status(s):
        return ('-', '-')

    project_root = os.environ.get('PROJECT_ROOT', '.')
-    candidates = [
+    # Issue #21: MAM_JOBS_DIR and the registry the row was created against
+    # (control_plane) first, then the matching audit logs, then the old ones.
+    cp = s.get('control_plane') or {}
+    candidates = [os.path.join(r, f"{jid}.json")
+                  for r in (os.environ.get('MAM_JOBS_DIR'), cp.get('mam_jobs_dir')) if r]
+    candidates += [os.path.join(r, jid, 'status.json')
+                   for r in (os.environ.get('DELEGATE_JOB_LOGS_DIR'), cp.get('delegate_job_logs_dir')) if r]
+    candidates += [
        os.path.join('.mam', 'jobs', f"{jid}.json"),
        os.path.join(project_root, '.mam', 'jobs', f"{jid}.json"),
        os.path.join(project_root, '.mam', 'delegate_job_logs', jid, 'status.json'),
@@ -361,7 +368,14 @@ def get_job_status(s):
    project_root = os.environ.get('PROJECT_ROOT', '.')
    # Candidate locations (review item 6: project-root-relative, no hardcoded abs paths):
    #   1) cwd-relative registry  2) project-root registry  3) project-root audit log
-    candidates = [
+    # Issue #21: MAM_JOBS_DIR and the registry the row was created against
+    # (control_plane) first, then the matching audit logs, then the old ones.
+    cp = s.get('control_plane') or {}
+    candidates = [os.path.join(r, f"{jid}.json")
+                  for r in (os.environ.get('MAM_JOBS_DIR'), cp.get('mam_jobs_dir')) if r]
+    candidates += [os.path.join(r, jid, 'status.json')
+                   for r in (os.environ.get('DELEGATE_JOB_LOGS_DIR'), cp.get('delegate_job_logs_dir')) if r]
+    candidates += [
        os.path.join('.mam', 'jobs', f"{jid}.json"),
        os.path.join(project_root, '.mam', 'jobs', f"{jid}.json"),
        os.path.join(project_root, '.mam', 'delegate_job_logs', jid, 'status.json'),
@@ -132,7 +132,8 @@ for s in d.get('herdr_sessions', []):
    if s.get('name') == name:
        cwd = (s.get('pane') or {}).get('cwd', '')
        jid = s.get('delegate_job_id', '') or ''
-        print(json.dumps({'cwd': cwd, 'job_id': jid}))
+        cp = s.get('control_plane') or {}
+        print(json.dumps({'cwd': cwd, 'job_id': jid, 'mam_jobs_dir': cp.get('mam_jobs_dir', '') or ''}))
        sys.exit(0)
 sys.exit(7)
 ") || {
@@ -142,6 +143,13 @@ sys.exit(7)

 TARGET_CWD=$(printf '%s' "$MAPPED_DATA" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("cwd",""))')
 DELEGATE_JOB_ID=$(printf '%s' "$MAPPED_DATA" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("job_id",""))')
+# Issue #21: a row created against another control plane names its registry.
+# Order: MAM_JOBS_DIR > the row's control_plane.mam_jobs_dir > WORKSPACE_ROOT >
+# .mam/jobs; exported so delegate_publish_event (lib.sh) uses the same one.
+ROW_JOBS_DIR=$(printf '%s' "$MAPPED_DATA" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("mam_jobs_dir",""))')
+if [ -z "${MAM_JOBS_DIR:-}" ] && [ -n "$ROW_JOBS_DIR" ]; then
+  export MAM_JOBS_DIR="$ROW_JOBS_DIR"
+fi
 DELEGATE_JOB_TOKEN=""
 DELEGATE_JOB_ATTEMPT=""
 if [ -n "$DELEGATE_JOB_ID" ]; then