feat(registry): push/pull + run agent/bundle from the registry (typed-artifact schema v2, mounts, filesets)

[msa0311]

Client integration between lns and the lns-registry: push/pull every artifact family and container images through one Docker-like verb pair, and run an agent or bundle artifact directly from the registry — including mounting application-layer artifacts (filesets) into the agent. (Registry login/logout is provided by #66, already on main; this PR builds on it.)

Commands

• lns push <source> <ref> [--family X] [--content <dir|file>] — source is a local file → pushed as the typed artifact for the family (inferred from the ref's …/<segment>/… path or --family); source is an image ref → re-pushes an image from lns's cache. --content packs a local dir/file into the artifact's OCI layer (fileset authoring).
• lns pull <ref> [-o file] — the registry's artifactType/config mediaType decides: a typed artifact is written out (file or stdout); an OCI image is pulled into the cache.
• lns run <agent-ref> / lns run <bundle-ref> [--mount <ref>[:/path]] — resolve a typed agent or bundle artifact into a concrete run and boot it; --mount attaches an application-layer artifact at the path it declares (see Running artifacts).
• lns run / image pull now authenticate to the registry too (stored credential + loopback-HTTP).

Generic, file-based: the registry is the schema authority (validates the config blob, MANIFEST_INVALID on failure). All 10 families ride one code path; no per-family Rust models. lns policy allow/deny/list/remove (local editing) unchanged.

Running artifacts

lns run <ref> accepts a typed agent or bundle artifact, not just an OCI image:

• agent → resolves to its image, command, and full run config — user, ports, volumes — plus its declared credentials.
• bundle (kind: AgentSystem) → resolves its single agent component (host-qualifying the ref against the bundle's registry), applies the sandbox profile (cpus/memory), and materializes the bundle's egress policy into a run-scoped ephemeral file, leaving the project's lns-policy.yaml untouched.
• --mount <ref>[:/path] → attaches an application-layer artifact (fileset/model/tool/knowledge) at the path the artifact declares in its mount (or an explicit :/path override). Now an optional override: a fileset the agent needs can ride in the bundle via components.filesets (below), so lns run <bundle> is self-contained. Explicit mounts coexist with bundle-resolved ones.
• The resolved run config overlays onto RunArgs with explicit CLI flags always winning (--cpus, -p, -v, --cmd, --policy, …).
• Required credentials with no usable local entry produce a non-fatal lns connect … warning (the sandbox still asks at the boundary) — not a hard block.
• A plain image or imageless run passes through unchanged; a non-runnable family (policy, tool, …) is refused with a clear message.

Typed-artifact schema v2 (two-class model + mounts)

Adopts lns-registry PR #5's redesigned schema (clean break, v1alpha1). Every family is runtime-layer (applied around the agent) or application-layer (mounted into the agent filesystem). Shared envelope {apiVersion, kind, metadata, mount?, spec} — all family content nests under spec.

• Families (10): added model + fileset; agent drops isolation (sandbox owns it); refs become ArtifactRef {ref, digest?}; bundle components gains model and filesets.
• Fileset authoring (push side). lns push --content walks a local dir/file into a single gzip-tar layer and threads it through RegistryClient::push_artifact → the PushArtifact IPC frame → the service's ArtifactRegistry → the OCI manifest, so a fileset's content lands in the registry as real image layers.
• Mounting (consume side). Application-layer artifacts are materialized into the guest at boot via the existing RuntimeFileSpec→composefs rail. model writes its envelope spec ({provider, model, parameters?}) at /etc/agent/model per the ARTIFACTS.md consume contract (mirrors the policy unwrap); tool/knowledge/fileset have their OCI layers fetched (pull_artifact_layers), gz-sniffed, tar-walked (tar-slip guarded by safe_rel_path), and injected under /etc/agent/tools|knowledge/<name> (or the fileset's explicit mount.path). The thin CLI resolver computes the mount path from each component's config blob and emits RunImageArgs.artifact_mounts {reference, path, read_only}; the service does the pull + untar at boot. read_only is advisory today (the seed lands in the read-only composefs base; per-file RO + overlay-CoW-shadow enforcement is future work).
• Policy normalization. materialize_policy unwraps the policy envelope's spec and rewrites each spec.integrations ArtifactRef ({ref}) to the bare integration id the supervisor reads, so a bundle policy that references integrations loads instead of failing on a type mismatch.

Architecture

• lns-policy artifact: family taxonomy (slug / media types / path-segment / inference, two-class is_application_layer) + YAML-or-JSON → JSON to_config_blob; typed deserializers (the registry-contract crate owns the schemas).
• lns-ipc: PushArtifact {…, layers} / PushImage / Pull; ArtifactMount {reference, path, read_only} on RunImageArgs/RunConfig.
• lns-service artifact: auth resolution + loopback/LNS_REGISTRY_PLAIN_HTTP protocol; artifact-vs-image decided from the manifest; image push reconstructs from the persisted image record; materialize_mounts pulls + expands application-layer layers into RuntimeFileSpecs folded into the runtime layer.
• lns-cli registry + run::resolve: thin IPC client; the resolver is a pure, injectable unit driven through the RegistryClient port (fully host-tested with a fake registry, no real I/O).

CLI stays a thin IPC client; the daemon owns the oci-client. Loopback registries (localhost/127.0.0.1/::1) auto-use plain HTTP, like Docker.

Tests / gate

Full local gate green (make lint && make complexity && make coverage, all touched crates 100%, 0 failures). Layer 2: registry.feature round-trips artifacts + image push + family inference; run_agent_ref.feature + run_bundle_ref.feature pin resolution/credential gate/ephemeral policy; run_mount_flag.feature pins --mount landing an ArtifactMount at the fileset's declared path (and an explicit override). Layer 3 covers the family contract, deserializers, blob conversion, the resolver (mapping + overlay precedence + every error path), the content-layer packer, the integration-ref normalizer, service materialization (gz-sniff, tar-walk, tar-slip guard), and the IPC codec. Coverage IGNOREs: the thin IPC leaves (registry/real.rs) and the OCI leaf in image/real.rs.

Live end-to-end verification (PR#5 registry + microVM)

Migrated the hermes demo (hermes-agent/lens/) to schema v2 and a config fileset: hermes is non-compliant (reads only $HERMES_HOME/config.yaml, never /etc/agent/*), so its config.yaml ships as a fileset mounted at /opt/data, replacing the old cp/sed config shim. Verified against the live registry + a real microVM:

• lns push fileset-config.yaml …/filesets/hermes-config:v1 --content filesets/hermes-config → accepted as 142 bytes + 1 layer; the registry manifest carries the gzip-tar layer; pulled back, it contains config.yaml.
• lns run …/bundles/hermes-system:v1 --mount …/filesets/hermes-config:v1 → resolved the agent, applied the sandbox (2 vCPU / 3072 MiB) and the materialized egress policy (16 allow rules, integration refs normalized), mounted the fileset at /opt/data, booted, and hermes came up reading the fileset config — its banner showed claude-sonnet-4-6 (the fileset's value, not the image default claude-opus-4.6), and api.anthropic.com traffic showed the anthropic integration injecting its credential.

Digest-pin fix (pull_inner). Digest-pinned pulls previously failed on a phantom mismatch: pull_inner re-hashed a serde re-serialization of the manifest and compared it to the requested digest, which (a) never matches for a multi-arch image — the pin is the index, which the client follows to a platform manifest — and (b) doesn't reproduce the registry's stored bytes, so the computed digest was fictional. The oci-client already verifies the requested digest against the raw bytes on fetch (index + resolved platform manifest), so the redundant re-check was dropped. Digest-pinned pulls, the sandbox baseImage pin, and lns run @sha256:… on multi-arch images now work.

Integrated with current main ✅

Merged current main and reconciled the divergence: dropped our duplicate login in favour of #66 (deleted auth/mod.rs + our colliding registry_auth.rs; adopted main's RegistryAuthStore/credential_for and rewired the service-side auth helpers to it), and ported push/pull/run --mount into main's CommandSpec registry (each is now a *_SPEC with the socket-wiring entry points in the real leaf, mirroring login). Reconciled main's host-bind feature (RunImageArgs.name/binds, the unified mounts: Vec<MountSpec> run flag) alongside our artifact_mounts, and kept our pull_inner digest fix (main still carried the bug). Full gate green (lint + complexity + 100% coverage across all crates); the branch is MERGEABLE.

Deferred (TODO)

• Local pre-push schema validation against GET /ext/v1/types (today: rely on server MANIFEST_INVALID).
• Multi-agent bundles.
• OS keyring; OIDC device/browser login; pushing images straight from the Docker daemon (not just lns's cache).

[jansav]

Login part was already implemented in #66

[msa0311]

Reviewed against the lns-registry PR #5 contract (registry-side author here). Overall: this is a faithful, careful adoption of the v2 schema — I'm happy with it. The schema mapping is exact and the mount/untar rail is genuinely well-built. A few points below; none are blockers.

Strong points

• Schema adoption is exact (lns-policy/src/artifact.rs): all 10 families, correct runtime/application split (is_application_layer), /etc/agent/* defaults matching the registry, ArtifactRef {ref,digest?}, model+fileset, bundle components.model, agent dropped isolation. The generic MountedArtifact reader (just {metadata, mount?}) is a nice way to mount any application-layer artifact without modelling every spec.
• The untar rail is secure, with defense in depth. Two independent gates — safe_rel_path (lns-service/src/artifact.rs) rejects ../absolute/non-UTF8 tar entries, and normalize_guest_path (runtime_layer/mod.rs) rejects .. again at build time. gz magic-byte sniff, duplicate-mount-path detection, family-gated dispatch (non-mountable family → hard error). This is the part I scrutinized hardest and it's right.
• Tests are thorough (behaviour features + unit coverage of deserializers, blob conversion, gzip layer expansion, the traversal guard).

Points worth addressing

1. Model mount format — the one real contract decision (let's align).
For model the code mounts the full envelope ({apiVersion,kind,metadata,spec}) at /etc/agent/model, whereas tool/knowledge/fileset mount raw layer files and policy is unwrapped to spec for the supervisor. What a compliant agent reads at /etc/agent/model is the standard, so I've now pinned it in the registry's docs/ARTIFACTS.md ("Mount file format — the consume contract"):

• model mounts its spec ({provider, model, parameters?}), not the full envelope — so the agent reads config directly without peeling a k8s-style wrapper (mirrors the policy unwrap; identity is already implied by the mount path).
• tool/knowledge/fileset mount layer files verbatim (no envelope).

PRISM hasn't implemented the layout yet, so we get to define it — proposing spec-only. This would be a ~one-line change here (unwrap spec like materialize_policy does). Happy to discuss if you/PRISM prefer the full envelope.

2. mount.path is now constrained registry-side. I added a schema rule on PR #5: mount.path must be absolute + traversal-free (leading /, no ..). So a bad fileset path now fails at push with a clear message rather than late in normalize_guest_path mid-boot. No change needed here — just a heads-up that the surface tightened.

3. read_only — parsed and threaded, but is it enforced? It reaches RunImageArgs.artifact_mounts{read_only}, but I didn't see it affect the composefs injection (everything goes in at mode & 0o7777). Worth confirming a readOnly: true mount is actually non-writable in the guest, or documenting it as advisory for now.

4. Symlink targets in layers are unsanitized (expand_layer_to_specs) — but they only ever resolve inside the guest's own FS, so not a host escape. Fine to leave; a one-line comment noting it's intentional would help the next reader.

The integrations ArtifactRef-vs-string mismatch you flagged is real and correctly deferred — that's the next thing to land before integrations work end-to-end.

[msa0311]

Follow-up on the deferred "bundle filesets component key (registry gap) + the paired lns run --mount flag" from this PR's description.

I've closed the registry gap on lns-registry PR #5: the bundle schema now has components.filesets: [ArtifactRef] (it was the only application-layer family missing from bundle composition — model/tools/knowledge were already there). GET /ext/v1/types reflects it, and a fileset-in-bundle validates.

So --mount no longer has to be required — a fileset the agent needs to boot can live in the bundle like everything else. Consume side here:

• Add filesets: Vec<ComponentRef> to Components (lns-policy/src/artifact.rs) — mirrors tools/knowledge.
• In the bundle resolver (lns-cli/src/run/resolve.rs), resolve components.filesets[] into RunImageArgs.artifact_mounts the same way the explicit --mount flag does — each fileset mounts at its envelope mount.path (already validated absolute + traversal-free registry-side now).
• Keep --mount as an optional override for ad-hoc/local use (a fileset not in the bundle, or lns run <agent> without one), with explicit flags winning over bundle-resolved mounts — consistent with how --cpus/-p/-v already overlay.

Net: lns run <bundle> becomes self-contained — no required --mount. Happy to coordinate ordering (registry PR #5 is ready to merge whenever).

[msa0311]

Thanks both — addressed in 8821dd5, with one item tracked as a deliberate follow-up.

@msa0311 (review points)

1. Model mount → spec-only. Done. Model mounts now unwrap the envelope spec, so /etc/agent/model carries {provider, model, parameters?} directly (mirrors the policy unwrap), per the pinned ARTIFACTS.md consume contract. Falls back to the full blob when there's no spec.
2. mount.path constraint — noted, no change needed here; thanks for tightening it registry-side.
3. read_only — confirmed it is not enforced today: RuntimeFileSpec has no RO/mode option and everything injects at mode & 0o7777. Documented as advisory at the materialize site (the seed lands in the read-only composefs base, but per-file RO mode + overlay-CoW-shadow enforcement is future work). Left the field threaded for when we do enforce it.
4. Symlink targets — added a one-line note that targets are intentionally verbatim: they resolve only inside the guest FS (never the host), and the entry path is already safe_rel_path-guarded.
5. Integrations ArtifactRef→string — already landed earlier in 1049127 (normalize_policy_integrations rewrites spec.integrations {ref} → the bare id the supervisor reads).

Bundle filesets (your follow-up): done. Components gained filesets: Vec<ComponentRef> and the bundle resolver mounts them at their declared mount.path, so lns run <bundle> is self-contained. --mount stays an optional override — explicit mounts coexist with bundle-resolved ones.

@jansav

You're right — #66 already ships lns login. Our branch carries a duplicate (auth/mod.rs + a colliding registry_auth.rs), and it's also 107 commits behind main, which has since reworked the CLI into the CommandSpec registry (no push/pull module yet). Dropping our login and porting our push/pull/run-resolve commands into that system is a sizable integration, so I'm tracking it as a dedicated follow-up rather than folding it into this round of review fixes. A pre-integration backup of the branch is kept locally.

[msa0311]

Integrated current main and the branch is now MERGEABLE (was 130 commits behind).

@jansav — our duplicate login is gone: dropped auth/mod.rs + our colliding registry_auth.rs, adopted #66's RegistryAuthStore/credential_for, and rewired the service-side auth helpers to it. lns login/logout are now solely #66's.

Also ported our push/pull/run --mount into main's new CommandSpec registry (socket-wiring entry points live in each module's real leaf, mirroring login), and reconciled the host-bind feature (RunImageArgs.name/binds + the unified mounts: Vec<MountSpec> flag) alongside artifact_mounts. Kept our pull_inner digest-pin fix (main still carried that bug — worth a separate look).

Full local gate is green (lint + complexity + 100% coverage, all crates); CI is running. Ready for another look. 🙏