Add castle secret CLI and fail-loud unresolved-secret apply gate

Writing a secret by hand meant knowing the active backend and its layout;
getting it wrong (a file write on an OpenBao fleet) left the value where the
resolver never reads it, so ${secret:NAME} silently degraded to the literal
<MISSING_SECRET:NAME> placeholder that a service then used as its credential.

- `castle secret {list|set|get|rm}` reads/writes the ACTIVE backend, so there's
  no wrong store to pick. `set NAME` with no value reads a hidden prompt / stdin.
- `castle apply` (and --plan) now refuses to converge any deployment whose
  ${secret:...} refs don't resolve in the active backend: exits non-zero, writes
  nothing, and names each deployment + secret + the `castle secret set` fix.
- New helpers in core/config.py: active_secret_backend(), active_backend_name(),
  secret_refs(). Gate impl: deploy._unresolved_secrets() + ApplyResult.blocked.
- Tests: test_deploy_secret_gate.py, TestSecretRefs, test_secret.py. Docs: AGENTS.md.

core/tests/test_config.py

@@ -12,6 +12,7 @@ from castle_core.config import (
     resolve_env_split,
     resolve_env_vars,
     save_config,
+    secret_refs,
 )
 from castle_core.manifest import ProgramSpec, SystemdDeployment
 
@@ -182,6 +183,22 @@ class TestResolveEnvVars:
         assert resolved["API_KEY"] == "<MISSING_SECRET:NONEXISTENT>"
 
 
+class TestSecretRefs:
+    """Tests for extracting ${secret:NAME} references (the apply-gate input)."""
+
+    def test_none_when_no_refs(self) -> None:
+        assert secret_refs("plain") == []
+        assert secret_refs("${port}/${data_dir}") == []
+
+    def test_single_and_composite(self) -> None:
+        assert secret_refs("${secret:API_KEY}") == ["API_KEY"]
+        assert secret_refs("neo4j/${secret:NEO4J_PW}") == ["NEO4J_PW"]
+
+    def test_multiple_deduped_in_order(self) -> None:
+        value = "${secret:A}:${secret:B}:${secret:A}"
+        assert secret_refs(value) == ["A", "B"]
+
+
 class TestResolveEnvSplit:
     """Tests for the secret/plain partition used to keep secrets out of units."""
 

core/tests/test_deploy_secret_gate.py

@@ -0,0 +1,65 @@
+"""Tests for the apply-time unresolved-secret gate.
+
+`castle apply` must refuse to converge a deployment whose ``${secret:NAME}`` env
+references the active backend can't resolve — otherwise the value silently
+degrades to a ``<MISSING_SECRET:NAME>`` placeholder and the service starts with a
+bogus credential (the immich-DB-password-to-the-wrong-backend failure).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from castle_core.deploy import _unresolved_secrets
+
+
+def _spec(env: dict[str, str], enabled: bool = True) -> SimpleNamespace:
+    return SimpleNamespace(enabled=enabled, defaults=SimpleNamespace(env=env))
+
+
+@pytest.fixture
+def file_backend(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Force the active backend to a temp file store with a known secret."""
+    secrets = tmp_path / "secrets"
+    secrets.mkdir()
+    (secrets / "PRESENT").write_text("value\n")
+    monkeypatch.setenv("CASTLE_SECRET_BACKEND", "file")
+    monkeypatch.setattr("castle_core.config.SECRETS_DIR", secrets)
+    return secrets
+
+
+def test_all_resolved_returns_empty(file_backend: Path) -> None:
+    items = [("service", "svc", _spec({"TOKEN": "${secret:PRESENT}"}))]
+    assert _unresolved_secrets(items) == []
+
+
+def test_missing_secret_is_reported(file_backend: Path) -> None:
+    items = [("service", "svc", _spec({"TOKEN": "${secret:ABSENT}"}))]
+    assert _unresolved_secrets(items) == [("svc", ["ABSENT"])]
+
+
+def test_disabled_deployment_skipped(file_backend: Path) -> None:
+    items = [("service", "svc", _spec({"TOKEN": "${secret:ABSENT}"}, enabled=False))]
+    assert _unresolved_secrets(items) == []
+
+
+def test_non_secret_placeholders_ignored(file_backend: Path) -> None:
+    items = [("service", "svc", _spec({"PORT": "${port}", "DIR": "${data_dir}"}))]
+    assert _unresolved_secrets(items) == []
+
+
+def test_composite_value_partial_missing(file_backend: Path) -> None:
+    # A URL mixing a present and an absent secret still flags the absent one.
+    env = {"URL": "postgres://u:${secret:PRESENT}@h/db?k=${secret:ABSENT}"}
+    assert _unresolved_secrets([("service", "svc", _spec(env))]) == [("svc", ["ABSENT"])]
+
+
+def test_multiple_deployments_only_broken_flagged(file_backend: Path) -> None:
+    items = [
+        ("service", "ok", _spec({"T": "${secret:PRESENT}"})),
+        ("service", "bad", _spec({"T": "${secret:ABSENT}"})),
+    ]
+    assert _unresolved_secrets(items) == [("bad", ["ABSENT"])]