DreamLake
  1. DreamLake
  2. Notes
  3. Lakeshore
  4. ML-Dash
  5. CLI

Nymph supervisor identity

Status: Ge reviewed the current workstream on 2026-09-13 and authorized merge. Implementation PR #21 merged as 6079ef7 on 2026-09-13 after Linux CI passed; Ge testing is not claimed. Nymph v0.1.5 binaries are published and verified. This note is published at docs.dreamlake.ai. Existing host rollout and live shared-cluster acceptance are not claimed. Tracking: Master #247, nymph issue #20, implementation PR #21.

2026-09-12 — ownership and verify-before-kill reporting

This entry records the implementation at nymph commit 7e4f42f, completed on 2026-09-07. PR status and CI were rechecked on 2026-09-12; this reporting update does not change runtime code.

On a shared login node, a control-plane Worker row alone cannot establish which local daemon or workload belongs to a supervisor. The proposed local contract adds a stable --supervisor-id / NYMPH_SUPERVISOR_ID, defaulting to hostname plus effective UID. Same-user supervisors need distinct explicit IDs. Signing identity and the control-plane Worker ID remain separate.

The daemon writes a private discovery record beneath $XDG_STATE_HOME/nymph/supervisors (fallback: ~/.local/state/nymph/supervisors), scoped by the supervisor-ID hash. Fields include supervisorId, instanceId, pid, uid and processStart; on Linux the start marker combines boot ID and process-start ticks. The opt-in loopback introspection server exposes live ownership through GET /ownership. Records can be stale after a hard exit or OTA; neither a record nor an answering port alone authorizes a kill.

Subprocesses and Slurm/container/pod workloads receive ownership markers. Cancellation checks retained child ownership and, on Linux, the live environment marker. Process groups are checked before TERM and again before KILL. Slurm cancellation checks job identity and UID; Docker/gVisor stop checks container ownership labels. A mismatch refuses cancellation without falling through to implicit child cleanup. Markers protect against accidental cross-supervisor cleanup, not malicious code running as the same OS user.

Validation and delivery evidence

  • Historical macOS validation: cargo fmt --check, cargo clippy and cargo test passed; 326 tests passed and six existing opt-in/doc tests were skipped. Apple Clang was selected because the ambient GCC could not find SDK headers.
  • Linux CI on the implementation revision passed formatting, Clippy and the full default test suite. Existing Clippy warnings remain. Refusal tests prove a foreign process survives and that missing, mismatching or ambiguous scheduler metadata never invokes scancel.
  • PR CI also passed; both results were rechecked, not rerun, for this note.
  • At this historical revision, implementation PR #21 was open. No merge, package release, production deployment or live shared-cluster acceptance is claimed. Real scheduler/container tests remain opt-in; mocked scheduler tests are not live Slurm acceptance.

Remaining work

  • Implementation merge, binary publication and docs publication are verified below; existing host rollout remains separate.
  • CLI: persist explicit supervisor IDs; scope discovery, tmux sessions and systemd units; verify live UID, executable/marker and process-start identity before adoption and each TERM/KILL; add per-slot crash and wedge backoff.
  • Verify cancellation and refusal on a real shared Slurm host and container runtime. CLI restart/reclaim acceptance remains outstanding.
  • Kubernetes workloads are stamped, but remote pod deletion/adoption semantics are unchanged and need a separate ownership design.

The CLI integration contract and implementation details record the exact boundary. See Unreleased.

2026-09-12 — docs integration after the foundation merge

The Dev Notes foundation in docs PR #262 has merged. This note's PR #273 is being integrated against main, preserving the other workstreams' index and Unreleased entries. Its navigation order is now distinct from compose capacity. This changes documentation integration only; nymph PR #21 remains open and no supervisor release, deployment or live acceptance is newly claimed.

2026-09-13 — review, current-main integration and test instructions

Ge confirmed review and authorized merging. This does not assert Ge tested the runtime. Integration with current nymph main preserves durable signed reconnect, signed raw logs and tracked uv execution. The tracked runner now stamps ownership and uses verified group cancellation, including drop cleanup. Once a leader is reaped, its cached PID no longer authorizes a group signal. If descendants retain capture pipes, draining fails explicitly after two seconds; those descendants may remain running. This limitation is preferable to an unverified group kill and still needs a separate descendant-discovery design.

New regression tests cover foreign-group refusal, refusal after leader reaping, and bounded capture draining. The integrated macOS suite passed 334 tests with six ignored, including 201 library tests; formatting and Clippy passed (existing warnings). Linux default checks and all-features tests passed on f54024e. PR #21 merged as 6079ef7. The full local docs build and rendered note/index/release link checks passed. The historical results above remain tied to their original revision.

How to test

Use a separate checkout, preserving any dirty working directory. Prerequisites: Rust with rustfmt/Clippy, Python 3 and uv on PATH, plus GitHub repository access.

sh
gh repo clone dreamlake-ai/nymph nymph-supervisor-review
cd nymph-supervisor-review
git checkout 6079ef77eefddde40b05de702fd5a1d42ec56173
uv --version
cargo fmt --check
cargo clippy
cargo test --lib supervisor::tests
cargo test --lib runner::slurm::tests::scancel_refuses_foreign_missing_and_ambiguous_ownership
cargo test --lib runner::tracked::tests
cargo test
cargo test --locked --all-features

On the test Mac, uv --version returned 0.12.2. If ambient GCC cannot find SDK headers, prefix the cargo commands with CC=/usr/bin/clang. Expected: every selected test runs and passes. Foreign-process/group tests must leave the target alive, scheduler refusal must never invoke scancel, and tracked uv tests cover real local Python output, failure, timeout, cancellation and bounded capture. Existing Clippy warnings and explicitly ignored external-runtime tests remain. Run on Linux too: the live /proc marker test is compiled only there; a successful macOS run does not cover that case. Linux CI installs uv before running the suite.

For the documentation, use a second clean checkout. The two UI source aliases require their pinned submodules and dependencies; they are build prerequisites, not changes to this workstream.

sh
gh repo clone dreamlake-ai/dreamlake-workspace supervisor-docs-review
cd supervisor-docs-review
gh pr checkout 273
git submodule update --init dreamlake-ai uikit-workspace
git -C dreamlake-ai submodule update --init packages/uikit-workspace
pnpm install --frozen-lockfile --ignore-scripts
pnpm --dir uikit-workspace install --frozen-lockfile --ignore-scripts --filter @dreamlake/uikit
pnpm --dir dreamlake-ai/packages/uikit-workspace install --frozen-lockfile --ignore-scripts --filter @dreamlake/uikit
pnpm --filter docs build
git diff --check

Expected: Vite, prerendering, llms generation and Pagefind finish successfully. Inspect docs/dist/client/dev/notes/nymph-supervisor-identity/index.html for How to test, the dated entry and status. The generated Dev Notes index and release-notes/index.html must link the supervisor note and retain the other workstreams. These are local build results, not deployment verification.

Not covered: live shared Slurm cancellation, real Docker/gVisor stop, CLI restart/adoption/backoff, remote Kubernetes ownership and production deployment. Do not run generic cleanup commands against existing shared-host daemons to test refusal. Real acceptance requires dedicated owned test jobs and separate markers.

2026-09-13 — v0.1.5 publication

Ge authorized release. Nymph v0.1.5 is published through the repository's tag-triggered release workflow for Linux x86_64, Linux arm64 and macOS arm64. Public versioned raw binaries and tarballs match their SHA-256 sidecars; every latest artifact matches the versioned artifact, and latest/VERSION reports v0.1.5. A clean macOS arm64 installation passed the installer checksum, reports nymph 0.1.5, and exposes --supervisor-id in help. Linux binaries were cross-built and checksum-verified; no live Linux host was upgraded for this release.

Release v0.1.5 and release PR #28, and release workflow record the build and publication evidence. Version-bump validation passed Linux default/all-features CI and 336 local macOS all-features tests (seven ignored). The docs site was deployed to the explicitly pinned Netlify site; the public note, index and release page were fetched and their content and links checked. Ge runtime testing is not claimed.

How to test the published release

Download the installer into a temporary directory and choose an empty installation directory so existing daemons and binaries are preserved:

sh
release_check_dir="$(mktemp -d)"
curl -fsSL https://pub-c0109e197b4a4d1abe5884ac4dd3a023.r2.dev/dreamlake/nymph/install.sh -o "$release_check_dir/install.sh"
mkdir "$release_check_dir/bin"
bash "$release_check_dir/install.sh" --version v0.1.5 --dest "$release_check_dir/bin"
"$release_check_dir/bin/nymph" --version
"$release_check_dir/bin/nymph" --help

Expected: checksum verification succeeds, version is nymph 0.1.5, and help lists --supervisor-id. These commands do not enroll, restart or stop a daemon. For source regression tests, use git checkout v0.1.5 in the isolated clone and run the runtime commands below. For docs, run pnpm --filter docs build after the listed dependency setup; expect successful prerender and generated note/index/ release pages. Fetch the three corresponding public URLs to verify publication.

Remaining work: CLI supervisor discovery/adoption/backoff, real shared Slurm and container acceptance, remote pod ownership, safe descendant discovery after leader exit, and rollout to existing hosts. Publication does not establish those outcomes.

Standing reporting checklist

For each subsequent coherent update to this workstream:

  • Append a dated entry here with How to test (commands, expected results and untested requirements); keep the Dev Notes index current.
  • Update Unreleased, separating implementation, merge, release and deployment.
  • DM Ge with source links until publication is verified, changes, validation and the next gap; record the verified sent-message link in issue #20 / PR #21.

Delivery evidence for this entry belongs in the linked trackers. These recurring items remain open for the next change; no autonomous watcher is installed.