docs(env): audit .env.example completeness after platform sprint (issue #782)

Adds two missing env vars to .env.example + docker-compose.yml platform block:

1. HIBERNATION_IDLE_MINUTES (default 60)
   Source: issue #724 / workspace hibernation feature.
   Note: currently configured per-workspace via the hibernation_idle_minutes
   DB column. This placeholder documents the planned global-default env var;
   the platform does not yet read it. Per-workspace DB column is active now.

2. PLUGIN_ALLOW_UNPINNED (empty = false)
   Source: issue #768 / PR #775 (supply chain hardening, not yet merged).
   Pre-emptive documentation — takes effect when PR #775 lands.

ADMIN_TOKEN (item 3): already present with clear generation instructions
(openssl rand -base64 32) and NEVER-commit reminder. No changes needed.

docker-compose.yml cross-check — vars present in .env.example but absent from
the platform service env block (flagged, not fixed in this PR — all have safe
compiled-in defaults and are optional):
  SECRETS_ENCRYPTION_KEY, AWARENESS_URL, MOLECULE_ENV, MOLECULE_IN_DOCKER,
  MOLECULE_ENABLE_TEST_TOKENS, MOLECULE_ORG_ID, CP_PROVISION_URL,
  ACTIVITY_RETENTION_DAYS, ACTIVITY_CLEANUP_INTERVAL_HOURS,
  REMOTE_LIVENESS_STALE_AFTER, PLUGIN_INSTALL_{BODY_MAX_BYTES,FETCH_TIMEOUT,
  MAX_DIR_BYTES}, TIER{2,3,4}_{MEMORY_MB,CPU_SHARES}, WORKSPACE_DIR.
These are not forwarded by docker-compose because they either auto-detect or
have safe defaults — operators override them via .env on the host. Adding
all of them to docker-compose would be noisy; a separate cleanup issue tracks
this.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -58,6 +58,13 @@ PLUGIN_INSTALL_BODY_MAX_BYTES=65536        # max request body size (default: 64
 PLUGIN_INSTALL_FETCH_TIMEOUT=5m            # duration string; whole fetch+copy deadline
 PLUGIN_INSTALL_MAX_DIR_BYTES=104857600     # max staged-tree size (default: 100 MiB)
 
+# ---- Plugin supply chain hardening (issue #768, PR #775) ----
+# Set to 'true' to allow unpinned plugin refs (no #tag/#sha). Local dev only.
+# When unset or 'false' (default), installing a plugin from a source without
+# an explicit ref is rejected — prevents supply chain attacks via floating HEAD.
+# NEVER set in production. Pending: PR #775 must merge before this takes effect.
+PLUGIN_ALLOW_UNPINNED=
+
 # Phase 30.7 — remote-agent liveness threshold. Workspaces with
 # runtime='external' are marked offline if their last_heartbeat_at is
 # older than this many seconds. Slightly larger than the 60s Redis TTL
@@ -65,6 +72,16 @@ PLUGIN_INSTALL_MAX_DIR_BYTES=104857600     # max staged-tree size (default: 100
 # the built-in default (90s).
 REMOTE_LIVENESS_STALE_AFTER=90
 
+# ---- Workspace hibernation (issue #724, PR #724) ----
+# Workspaces with no active tasks hibernate after this many minutes.
+# Leave empty to disable. Per-workspace override via the hibernation_idle_minutes
+# column (set via PATCH /workspaces/:id or org.yaml). This env var sets the
+# platform-wide default applied to workspaces that have no per-workspace setting.
+# Note: the global-default behaviour (reading this env var) is pending — currently
+# only the per-workspace DB column is active. Setting this has no effect until that
+# code lands.
+HIBERNATION_IDLE_MINUTES=60
+
 # Canvas
 NEXT_PUBLIC_PLATFORM_URL=http://localhost:8080
 NEXT_PUBLIC_WS_URL=ws://localhost:8080/ws

docker-compose.yml

@@ -144,6 +144,12 @@ services:
       # Generate: openssl rand -base64 32
       # Store in fly secrets / deployment env — NEVER commit the actual value.
       ADMIN_TOKEN: "${ADMIN_TOKEN:-}"
+      # Workspace hibernation default (issue #724 / PR #724). Sets platform-wide idle
+      # threshold (minutes); per-workspace column takes precedence. Leave empty to
+      # rely on per-workspace config only (current behaviour — global-default code pending).
+      HIBERNATION_IDLE_MINUTES: "${HIBERNATION_IDLE_MINUTES:-}"
+      # Plugin supply chain hardening (issue #768 / PR #775). Never set in production.
+      PLUGIN_ALLOW_UNPINNED: "${PLUGIN_ALLOW_UNPINNED:-}"
     volumes:
       - ./workspace-configs-templates:/configs
       - ./org-templates:/org-templates:ro