feat(memory-primitive): Phase 2 — hindsight adapter + e2e integration tests

Adds the first provider adapter under
providers/workspaces/claude-cli/memory/hindsight/:

- init.sh — translates AGENTIC_MEMORY_* contract into HINDSIGHT_* env
  vars. Sets HINDSIGHT_DYNAMIC_BANK_ID=false explicitly (so the env
  var HINDSIGHT_BANK_ID actually takes effect — verified empirically
  in agentic-memory probe bank-derivation-modes). Writes
  ~/.hindsight/claude-code.json when AGENTIC_MEMORY_CONFIG_JSON is
  supplied.
- doctor.sh — provider-specific health check (called from Python's
  ProviderSpecificCheck). Verifies the backend's GET /v1/default/banks
  returns 200 and checks bank membership ("not in list" = lazy-create
  pending = pass). Auto-fixes stale ~/.hindsight/claude-code.json
  configs that set dynamicBankId:true (a stale-state issue where
  HINDSIGHT_BANK_ID env override is silently ignored). Python is used
  for JSON parsing — robust against malformed configs.

API discovery: hindsight 0.6.x no longer supports
GET /v1/default/banks/<id> (returns 405). doctor.sh uses the list
endpoint and filters in Python.

Integration tests at tests/integration/test_entrypoint_memory.py
mirror test_entrypoint_workspace_injection.py:

  1. No provider → entrypoint completes normally (sections 5.6/5.7 no-op)
  2. Provider + reachable backend → doctor pass, adapter env vars
     exported, AGENTIC_MEMORY_READY=1, audit JSONL written
  3. Provider + unreachable backend → doctor fail, container exits 1
  4. Provider + missing namespace → env_contract check fails
  5. Unknown provider name → provider_known check fails
  6. Stale dynamicBankId:true config → auto-fixed to false,
     other keys preserved
  7. /opt/agentic/memory/doctor with no provider → exit 0 (no-op)
  8. /opt/agentic/memory/doctor --json → JSON to stdout, exit 1

8/8 integration tests passing against the rebuilt
agentic-workspace-claude-cli:latest image. Combined with 53 unit
tests in lib/python/agentic_memory/, full coverage of the contract
+ doctor + adapter end-to-end.

Discovered + fixed during testing:
- API endpoint shape change (GET /banks/<id> → use list endpoint)
- Entrypoint log lines go to stdout per existing convention (not
  stderr) — tests updated accordingly

Author: NeuralEmpowerment

providers/workspaces/claude-cli/memory/hindsight/doctor.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Hindsight provider-specific health checks (ADR-036 check 8).
+#
+# Called by /opt/agentic/memory/doctor's ProviderSpecificCheck. Reports
+# JSON to stdout describing findings; exit 0 = pass, exit 1 = fail.
+#
+# Checks:
+#   - bank_reachable: GET /v1/default/banks/<bank>
+#       200 = bank exists (good)
+#       404 = bank does not exist yet — fine, hindsight lazy-creates on
+#             first retain. Still considered pass.
+#       other = fail.
+#   - dynamic_bank_id_consistent: if ~/.hindsight/claude-code.json exists
+#       and has dynamicBankId !== false, the HINDSIGHT_BANK_ID env var
+#       the adapter set is silently ignored by the hindsight plugin
+#       (verified in hindsight bank.py:97). Auto-fix: rewrite the file
+#       with dynamicBankId: false. This is a stale-state issue, not an
+#       operator decision.
+
+set -e
+
+emit_json() {
+    local status="$1"
+    local details="$2"
+    printf '{"hindsight_provider_check":"%s","details":%s}\n' "$status" "$details"
+}
+
+# --- Check 1: bank_reachable --------------------------------------------------
+# Hindsight 0.6.x does not expose `GET /v1/default/banks/<id>` (returns 405).
+# Use the list endpoint and filter — "not in list" is fine because hindsight
+# lazy-creates banks on first retain.
+LIST_URL="${HINDSIGHT_API_URL}/v1/default/banks"
+HTTP_STATUS=$(curl -sS -o /tmp/hindsight-doctor-body -w "%{http_code}" \
+    --max-time 5 \
+    ${HINDSIGHT_API_TOKEN:+-H "Authorization: Bearer ${HINDSIGHT_API_TOKEN}"} \
+    "${LIST_URL}" || echo "000")
+
+if [ "${HTTP_STATUS}" != "200" ]; then
+    emit_json "fail" "$(printf '{"check":"bank_reachable","url":"%s","http_status":"%s","body_preview":"%s"}' \
+        "${LIST_URL}" "${HTTP_STATUS}" "$(head -c 200 /tmp/hindsight-doctor-body 2>/dev/null | tr '\n' ' ')")"
+    exit 1
+fi
+
+# Check membership. If the bank is in the list, status=exists; otherwise
+# lazy-create-pending (both pass).
+bank_status=$(python3 -c "
+import json, sys
+try:
+    with open('/tmp/hindsight-doctor-body') as f:
+        data = json.load(f)
+    banks = data.get('banks', [])
+    bank_ids = [b.get('bank_id') for b in banks if isinstance(b, dict)]
+    print('exists' if '${HINDSIGHT_BANK_ID}' in bank_ids else 'lazy_create_pending')
+except Exception:
+    print('lazy_create_pending')
+" 2>/dev/null || echo "lazy_create_pending")
+
+# --- Check 2: dynamic_bank_id_consistent (with auto-fix) ----------------------
+HINDSIGHT_CONFIG="${HOME}/.hindsight/claude-code.json"
+config_action="no_config_file"
+
+if [ -f "${HINDSIGHT_CONFIG}" ]; then
+    # Parse dynamicBankId field; default to false if file is malformed or key
+    # absent. Use python3 (always present in this image) for robust JSON parsing.
+    dyn_bank_id=$(python3 -c "
+import json, sys
+try:
+    with open('${HINDSIGHT_CONFIG}') as f:
+        cfg = json.load(f)
+    print('true' if cfg.get('dynamicBankId') else 'false')
+except Exception:
+    print('parse-error')
+" 2>/dev/null || echo "parse-error")
+
+    case "${dyn_bank_id}" in
+        false)
+            config_action="config_consistent"
+            ;;
+        true)
+            # Auto-fix: rewrite with dynamicBankId: false. The contract's intent
+            # is explicit bank-id; a stale config saying otherwise is wrong.
+            python3 -c "
+import json
+with open('${HINDSIGHT_CONFIG}') as f:
+    cfg = json.load(f)
+cfg['dynamicBankId'] = False
+with open('${HINDSIGHT_CONFIG}', 'w') as f:
+    json.dump(cfg, f, indent=2)
+" 2>/dev/null
+            config_action="auto_fixed_dynamic_bank_id"
+            ;;
+        parse-error)
+            emit_json "fail" "$(printf '{"check":"dynamic_bank_id_consistent","error":"config_file_unreadable","path":"%s"}' "${HINDSIGHT_CONFIG}")"
+            exit 1
+            ;;
+    esac
+fi
+
+# Success: emit a single JSON object with both check results.
+emit_json "ok" "$(printf '{"bank":"%s","bank_status":"%s","config_action":"%s"}' \
+    "${HINDSIGHT_BANK_ID}" "${bank_status}" "${config_action}")"
+exit 0

providers/workspaces/claude-cli/memory/hindsight/init.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Hindsight memory provider adapter.
+#
+# Translates the AGENTIC_MEMORY_* contract (ADR-036) into the HINDSIGHT_*
+# env vars the hindsight Claude Code plugin reads.
+#
+# Called by /opt/agentic/entrypoint.sh section 5.6 when
+# AGENTIC_MEMORY_PROVIDER=hindsight. Sourced into the parent shell so the
+# exports propagate to subsequent process spawns.
+#
+# Provider-specific failure modes are caught by /opt/agentic/memory/doctor
+# via this directory's `doctor.sh` (called from section 5.7).
+
+set -e
+
+# --- Backend URL --------------------------------------------------------------
+export HINDSIGHT_API_URL="${AGENTIC_MEMORY_URL}"
+
+# --- Auth (optional) ----------------------------------------------------------
+if [ -n "${AGENTIC_MEMORY_AUTH:-}" ]; then
+    export HINDSIGHT_API_TOKEN="${AGENTIC_MEMORY_AUTH}"
+fi
+
+# --- Bank scoping -------------------------------------------------------------
+# HINDSIGHT_BANK_ID env override is honored only when dynamicBankId=false
+# (verified empirically in agentic-memory's bank-derivation-modes probe).
+# Force static bank-id mode so the contract's namespace actually takes effect.
+export HINDSIGHT_DYNAMIC_BANK_ID=false
+export HINDSIGHT_BANK_ID="${AGENTIC_MEMORY_NAMESPACE}"
+
+# --- Optional rich config -----------------------------------------------------
+# AGENTIC_MEMORY_CONFIG_JSON is the escape hatch for adapter-specific config
+# the core contract doesn't model (e.g. recallAdditionalBanks). Written to
+# the path the hindsight plugin already knows how to read.
+if [ -n "${AGENTIC_MEMORY_CONFIG_JSON:-}" ]; then
+    mkdir -p "${HOME}/.hindsight"
+    printf '%s' "${AGENTIC_MEMORY_CONFIG_JSON}" > "${HOME}/.hindsight/claude-code.json"
+fi

tests/integration/test_entrypoint_memory.py

@@ -0,0 +1,233 @@
+"""Integration tests for the memory primitive entrypoint sections 5.6 + 5.7.
+
+Mirrors the pattern in test_entrypoint_workspace_injection.py — runs the
+real workspace container with varying AGENTIC_MEMORY_* env vars and
+asserts the doctor behavior end-to-end.
+
+Some tests require a running hindsight backend reachable at
+host.docker.internal:9077. They are skipped when the backend is
+unreachable; you can spin one up via either:
+
+    uvx hindsight-embed@latest daemon --profile claude-code start
+
+Or via the agentic-memory repo's docker compose stack.
+
+See ADR-036 + spec 2026-05-13-memory-primitive-and-doctor-design.md.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+IMAGE = os.getenv("AGENTIC_WORKSPACE_IMAGE", "agentic-workspace-claude-cli:latest")
+HINDSIGHT_BACKEND_URL = os.getenv(
+    "HINDSIGHT_BACKEND_URL_FROM_HOST",
+    "http://127.0.0.1:9077",
+)
+
+
+def _hindsight_reachable() -> bool:
+    """True if the hindsight backend's /health responds 200 from the host."""
+    try:
+        with urllib.request.urlopen(  # noqa: S310
+            f"{HINDSIGHT_BACKEND_URL}/health",
+            timeout=2,
+        ) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, TimeoutError, OSError):
+        return False
+
+
+def _run(
+    args: list[str],
+    env: dict[str, str] | None = None,
+    extra_mounts: list[str] | None = None,
+    add_host_gateway: bool = False,
+) -> subprocess.CompletedProcess:
+    """Run the workspace image with tmpfs home, optional env / mounts."""
+    cmd = [
+        "docker", "run", "--rm",
+        "--tmpfs=/home/agent:rw,exec,nosuid,size=128m,uid=1000,gid=1000",
+    ]
+    if add_host_gateway:
+        cmd.extend(["--add-host=host.docker.internal:host-gateway"])
+    for m in extra_mounts or []:
+        cmd.extend(["-v", m])
+    for k, v in (env or {}).items():
+        cmd.extend(["-e", f"{k}={v}"])
+    cmd.append(IMAGE)
+    cmd.extend(args)
+    return subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+
+
+@pytest.mark.integration
+def test_no_provider_is_noop():
+    """When AGENTIC_MEMORY_PROVIDER is unset, sections 5.6 + 5.7 do nothing."""
+    result = _run(["echo", "agent reached"])
+    assert result.returncode == 0, f"container failed: {result.stderr}"
+    assert "agent reached" in result.stdout
+    assert "memory doctor" not in result.stderr
+    assert "memory adapter" not in result.stderr
+
+
+@pytest.mark.integration
+@pytest.mark.skipif(not _hindsight_reachable(), reason="hindsight backend unreachable")
+def test_provider_with_reachable_backend_passes(tmp_path: Path):
+    """Reachable backend + valid env → doctor passes, adapter sets HINDSIGHT_*."""
+    audit_dir = tmp_path / "audit"
+    audit_dir.mkdir()
+
+    result = _run(
+        [
+            "bash", "-c",
+            "echo agent reached; "
+            "echo HINDSIGHT_BANK_ID=$HINDSIGHT_BANK_ID; "
+            "echo HINDSIGHT_API_URL=$HINDSIGHT_API_URL; "
+            "echo HINDSIGHT_DYNAMIC_BANK_ID=$HINDSIGHT_DYNAMIC_BANK_ID; "
+            "echo AGENTIC_MEMORY_READY=$AGENTIC_MEMORY_READY",
+        ],
+        env={
+            "AGENTIC_MEMORY_PROVIDER": "hindsight",
+            "AGENTIC_MEMORY_NAMESPACE": "integration-test-pass",
+            "AGENTIC_MEMORY_URL": "http://host.docker.internal:9077",
+        },
+        extra_mounts=[f"{audit_dir}:/var/agentic/memory-doctor"],
+        add_host_gateway=True,
+    )
+
+    assert result.returncode == 0, f"container failed: {result.stderr}"
+    combined = result.stdout + result.stderr
+    assert "agent reached" in result.stdout
+    assert "HINDSIGHT_BANK_ID=integration-test-pass" in result.stdout
+    assert "HINDSIGHT_API_URL=http://host.docker.internal:9077" in result.stdout
+    assert "HINDSIGHT_DYNAMIC_BANK_ID=false" in result.stdout
+    assert "AGENTIC_MEMORY_READY=1" in result.stdout
+    # Entrypoint log lines go to stdout (matches existing entrypoint convention)
+    assert "memory doctor: pass" in combined
+    assert "memory adapter: hindsight" in combined
+
+    audit_files = list(audit_dir.glob("*.jsonl"))
+    assert len(audit_files) == 1
+    payload = json.loads(audit_files[0].read_text().splitlines()[-1])
+    assert payload["status"] == "ok"
+    assert payload["exit_code"] == 0
+    assert payload["provider"] == "hindsight"
+
+
+@pytest.mark.integration
+def test_provider_with_unreachable_backend_hard_fails():
+    """Backend unreachable → doctor exits 1; container does NOT reach CMD."""
+    result = _run(
+        ["echo", "should not reach here"],
+        env={
+            "AGENTIC_MEMORY_PROVIDER": "hindsight",
+            "AGENTIC_MEMORY_NAMESPACE": "bad-backend-test",
+            "AGENTIC_MEMORY_URL": "http://nonexistent.invalid:9999",
+        },
+    )
+
+    assert result.returncode != 0
+    assert "should not reach here" not in result.stdout
+    # FAIL log message goes to stderr per the entrypoint section 5.7
+    assert "memory doctor: FAIL" in result.stdout + result.stderr
+
+
+@pytest.mark.integration
+def test_provider_with_missing_namespace_hard_fails():
+    """env_contract check catches missing required vars."""
+    result = _run(
+        ["echo", "should not reach here"],
+        env={
+            "AGENTIC_MEMORY_PROVIDER": "hindsight",
+            "AGENTIC_MEMORY_URL": "http://host.docker.internal:9077",
+        },
+        add_host_gateway=True,
+    )
+
+    assert result.returncode != 0
+    assert "should not reach here" not in result.stdout
+
+
+@pytest.mark.integration
+def test_unknown_provider_hard_fails():
+    """provider_known check catches typo'd provider names."""
+    result = _run(
+        ["echo", "should not reach here"],
+        env={
+            "AGENTIC_MEMORY_PROVIDER": "nonexistent-provider",
+            "AGENTIC_MEMORY_NAMESPACE": "x",
+            "AGENTIC_MEMORY_URL": "http://host.docker.internal:9077",
+        },
+        add_host_gateway=True,
+    )
+
+    assert result.returncode != 0
+    assert "should not reach here" not in result.stdout
+
+
+@pytest.mark.integration
+@pytest.mark.skipif(not _hindsight_reachable(), reason="hindsight backend unreachable")
+def test_auto_fix_stale_dynamic_bank_id(tmp_path: Path):
+    """Stale ~/.hindsight/claude-code.json with dynamicBankId:true is
+    auto-rewritten to false. The HINDSIGHT_BANK_ID env var the adapter
+    exports would otherwise be silently ignored by the hindsight plugin."""
+    home = tmp_path / "agent-home"
+    home.mkdir()
+    config = home / "claude-code.json"
+    config.write_text(json.dumps({
+        "dynamicBankId": True,
+        "dynamicBankGranularity": ["project"],
+        "stale_marker": "should-be-preserved",
+    }))
+
+    result = _run(
+        ["echo", "agent reached"],
+        env={
+            "AGENTIC_MEMORY_PROVIDER": "hindsight",
+            "AGENTIC_MEMORY_NAMESPACE": "test-autofix",
+            "AGENTIC_MEMORY_URL": "http://host.docker.internal:9077",
+        },
+        extra_mounts=[f"{home}:/home/agent/.hindsight"],
+        add_host_gateway=True,
+    )
+
+    assert result.returncode == 0, f"container failed: {result.stderr}"
+    assert "agent reached" in result.stdout
+
+    rewritten = json.loads(config.read_text())
+    assert rewritten["dynamicBankId"] is False
+    assert rewritten["stale_marker"] == "should-be-preserved"
+
+
+@pytest.mark.integration
+def test_doctor_binary_runs_without_provider():
+    """`/opt/agentic/memory/doctor` invoked with no provider is a no-op (exit 0)."""
+    result = _run(["/opt/agentic/memory/doctor"])
+    assert result.returncode == 0
+    assert "not opted in" in result.stderr.lower() or "no checks run" in result.stderr.lower()
+
+
+@pytest.mark.integration
+def test_doctor_binary_json_output():
+    """--json emits machine-readable output on stdout."""
+    result = _run(
+        [
+            "/opt/agentic/memory/doctor",
+            "--json",
+            "--provider", "nonexistent-provider",
+            "--namespace", "test",
+            "--url", "http://nonexistent.invalid:9999",
+        ],
+    )
+    assert result.returncode == 1
+    payload = json.loads(result.stdout.strip().splitlines()[-1])
+    assert payload["status"] == "fail"
+    assert payload["exit_code"] == 1
+    assert any(c["name"] == "provider_known" and c["status"] == "fail" for c in payload["checks"])