zlh-grind/SESSION_LOG.md

Session Log – zlh-grind

Append-only execution log for GPT-assisted development work.
Do not rewrite or reorder past entries.

---

2025-12-20

• Goal: Restore reliable end-to-end provisioning for devcontainers and agent-managed installs.
• Observed repeated failures during devcontainer runtime installation (node, python, go, java).
• Initial assumption was installer regression; investigation showed installers were enforcing contract correctly.
• Root cause identified: agent was not exporting required runtime environment variables (notably RUNTIME_VERSION).

---

2025-12-21

• Deep dive on zlh-agent devcontainer provisioning flow.
• Confirmed that all devcontainer installers intentionally require RUNTIME_VERSION and fail fast if missing.
• Clarified that payload JSON is not read by installers; agent must project intent via environment variables.
• Verified that installer logic itself (artifact naming, extraction, symlink layout) was correct.

Embedded installer execution findings

• Agent executes installers as embedded scripts, not filesystem paths.
• Identified critical requirement: shared installer logic (common.sh) and runtime installer must execute in the same shell session.
• Failure mode observed: install_runtime: command not found → caused by running runtime installer without common.sh loaded.
• Confirmed this explains missing runtime directories and lack of artifact downloads.

Installer architecture changes

• Refactored installer model to:
  • common.sh: shared, strict, embedded-safe installation logic
  • per-runtime installers (node, python, go, java) as declarative descriptors only
• Established that runtime installers are intentionally minimal and declarative by design.
• Confirmed that this preserves existing runtime layout: /opt/zlh/runtime/<language>/<version>/current

Artifact layout update

• Artifact naming and layout changed to simplified form:
  • node-24.tar.xz
  • python-3.12.tar.xz
  • go-1.22.tar.gz
  • jdk-21.tar.gz
• Identified mismatch between runtime name and archive prefix (notably Java).
• Introduced ARCHIVE_PREFIX as a runtime-level variable to resolve naming cleanly.

Final conclusions

• No regression in installer logic; failures were execution-order and environment-projection issues.
• Correct fix is agent-side:
  • concatenate common.sh + runtime installer into one bash invocation
  • inject RUNTIME_VERSION (and related vars) into environment
• Architecture now supports deterministic, artifact-driven, embedded-safe installs.

Status: Root cause resolved; implementation pending agent patch & installer updates.

---